linkd api documentation - read the docs · · 2013-05-02linkd api documentation, release 0.1...

Linkd API DocumentationRelease 0.1

Eric Barch

May 01, 2013

CONTENTS

1 API 31.1 Auth Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Connection Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 IRC Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2 Events 132.1 registered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.2 motd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.3 names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.4 topic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.5 join . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142.6 part . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.7 quit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.8 kick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152.9 kill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162.10 message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162.11 notice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172.12 nick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172.13 pm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172.14 invite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.15 +mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182.16 -mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.17 whois . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192.18 error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.19 channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202.20 channel_details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

3 Indices and tables 21

i

Linkd API Documentation, Release 0.1

Contents:

CONTENTS 1


2 CONTENTS

CHAPTER

ONE

API

1.1 Auth Commands

1.1.1 fb_auth

Authenticates with Linkd via Facebook token. If the user does not yet exist in the system, an account isautomatically generated. This is the first call that must be made to the API before any subsequent requests.

Example Request Payload:

{"token": "AAACEdEose0cBAIfGQIZAqjPN1gGMTdIvYyHGRbpOHqArQUKE1PAFZA5uy0FMn08ZAyRo1GHo83GV6FgD51yPWJslC7CxwDDO2s5sP8M5QZDZD"

}

Example Successful Response Payload:

{"success": true,"id": 835910294,"first_name": "Mop","last_name": "Squeegee"

}

Example Failed Response Payload:

{"success": false,"reason": "invalid_token"

}

Fail Reasons:

invalid_token: Facebook token could not be used to login or is malformedno_fb_token: A token was not included in the request payload

1.2 Connection Commands

1.2.1 create_connection

Creates a new IRC connection linked to the authenticated account.


3


{"label": "No Fat Chix Net","hostname": "irc.nofatchix.io","port": 6667,"nick": "lolskrillex","ssl": false,"server_password": "","nickserv_password": "","nickserv_enabled": false,"real_name": "Skrillex, Bro"

}


{"success": true,"connId": "50d68a2b7bf23fc51f000001"

}

Fail Reasons:

not_authed: You must first authenticate with the APIinvalid_connection: Invalid details were provided for the connection

1.2.2 edit_connection

Edits an existing IRC connection linked to the authenticated account.


{"connId": "50d68a2b7bf23fc51f000001","label": "No Fat Chix Net","hostname": "irc.nofatchix.io","port": 6667,"nick": "lolskrillex","ssl": false,"server_password": "","nickserv_password": "","nickserv_enabled": false,"real_name": "Skrillex, Bro"

}



}

Fail Reasons:

not_authed: You must first authenticate with the APIinvalid_connection: Invalid details were provided for the connection or the connection could not befound

4 Chapter 1. API


1.2.3 remove_connection

Removes an existing IRC connection linked to the authenticated account.


{"connId": "50d68a2b7bf23fc51f000001"

}



}

Fail Reasons:

not_authed: You must first authenticate with the APIinvalid_connection: The connection could not be found

1.2.4 connection_go_online

Requests that an IRC connection be brought online.


{"connId": "50d68a2b7bf23fc51f000001"

}



}

Fail Reasons:


1.2.5 connection_go_offline

Requests that an IRC connection be brought offline (and disabled).


{"connId": "50d68a2b7bf23fc51f000001"

}


1.2. Connection Commands 5



}

Fail Reasons:


1.2.6 get_all_connections

Returns the connection details of all connections linked to this account.


{}


{"success": true,"connections": [

{"connId": "50d68a2b7bf23fc51f000001","label": "No Fat Chix Net","hostname": "irc.nofatchix.io","port": 6667,"nick": "lolskrillex","ssl": false,"online": true,"away": "Being chased by some scary monsters and nice sprites","server_password": "","nickserv_password": "","nickserv_enabled": false,"sasl_enabled": false,"real_name": "Skrillex, Bro","channels": [{"name":"#dubstep","chanserv_enabled": false,"chanserv_password": ""

},{"name":"#hipsters","chanserv_enabled": false,"chanserv_password": ""

},{"name":"#bacon","chanserv_enabled": false,"chanserv_password": ""

}],"creation": 1356237355929,"disabled": false,"disabled_timeout": 1356237355929,"disabled_reason": "User initiated.",

6 Chapter 1. API


"online": false}

]}

Fail Reasons:

not_authed: You must first authenticate with the APIserver_error: Something went horribly wrong, ABORT

1.3 IRC Commands

1.3.1 join

Join an IRC channel. Any join errors will be received as events rather than a direct callback. If the joinwas successful, Linkd will add this channel to the user’s channel list.


{"connId": "50d68a2b7bf23fc51f000001","channel": "#lolcats"

}


{"success": true

}

Fail Reasons:

not_authed: You must first authenticate with the APInot_subbed: This session is not subscribed to the provided connection

1.3.2 part

Part an IRC channel. Any part errors will be received as events rather than a direct callback. If the partwas successful, Linkd will remove this channel from the user’s channel list.


{"connId": "50d68a2b7bf23fc51f000001","channel": "#lolcats"

}


{"success": true

}

Fail Reasons:


1.3. IRC Commands 7


1.3.3 say

Send a message to a user or channel. Any say errors will be received as events rather than a direct callback.


{"connId": "50d68a2b7bf23fc51f000001","to": "#lolcats","text": "omg cats"

}


{"success": true

}

Fail Reasons:


1.3.4 action

Perform an action in a channel or private message. Any action errors will be received as events rather thana direct callback.


{"connId": "50d68a2b7bf23fc51f000001","to": "#lolcats","text": "hugs cats"

}


{"success": true

}

Fail Reasons:


1.3.5 whois

Request a whois of a user. Whois data will be returned as another event if successful.


{"connId": "50d68a2b7bf23fc51f000001","to": "thatonecreepydude",

}


8 Chapter 1. API


{"success": true

}

Fail Reasons:


1.3.6 topic

Change the topic of a channel. Any topic errors will be received as events rather than a direct callback.


{"connId": "50d68a2b7bf23fc51f000001","to": "#lolcats","topic": "LOLCATS: the other, other white meat"

}


{"success": true

}

Fail Reasons:


1.3.7 nick

Change your nick. Any nick errors will be received as events rather than a direct callback.


{"connId": "50d68a2b7bf23fc51f000001","nick": "theNEWguy"

}


{"success": true

}

Fail Reasons:


1.3. IRC Commands 9


1.3.8 command

Send a raw IRC command. Any command errors will be received as events rather than a direct callback.


{"connId": "50d68a2b7bf23fc51f000001","command": "PRIVMSG","args": "#irchacks :Hello everybody!"

}


{"success": true

}

Fail Reasons:


1.3.9 get_log

Get the transcripts (backlog) for a particular channel. Currently returns up to 200 messages.


{"connId": "50d68a2b7bf23fc51f000001","channel": "#lava",

}


{"success": true,"log": [

{"ts":1356237355929,"from":"thedude","text":"what’s up guys"

},{

"ts":1356237355933,"from":"theotherdude","text":"not much bro"

}]

}

Fail Reasons:


10 Chapter 1. API


1.3.10 get_private_messages

Get all recent private messages.


{"connId": "50d68a2b7bf23fc51f000001","markRead": true

}


{"success": true,"messages": [

{"ts":1356237355966,"from":"thedude","text":"omg you need to reply to me ASAP"

},{

"ts":1356237355980,"from":"theotherdude","text":"i miss you, bro"

}]

}

Fail Reasons:


1.3.11 get_channels

Get all channels that are currently joined in this IRC session.


{"connId": "50d68a2b7bf23fc51f000001"

}


{"success": true

}

Fail Reasons:


1.3.12 get_channel_details

Get all channel details (topic, mode, userlist) for a joined channel.

1.3. IRC Commands 11



{"connId": "50d68a2b7bf23fc51f000001","channel": "#cats"

}


{"success": true

}

Fail Reasons:


12 Chapter 1. API

CHAPTER

TWO

EVENTS

2.1 registered

Emitted when the server sends the initial 001 line, indicating you’ve connected to the IRC server.

Event Payload:

{"connId": "50d68a2b7bf23fc51f000001","message": "REG MESSAGE FROM SERVER"

}

Fields:

connId: The ID of the IRC connectionmessage: The registered message from the server

2.2 motd

Emitted when the server sends the message of the day to clients.

Event Payload:

{"connId": "50d68a2b7bf23fc51f000001","motd": "SERVER MOTD"

}

Fields:

connId: The ID of the IRC connectionmotd: The server’s motd

2.3 names

Emitted when the server sends a list of nicks for a channel (which happens immediately after joining andon request. The nicks object passed to the callback is keyed by nick names, and has values ‘’, ‘+’, or ‘@’depending on the level of that nick in the channel.

Event Payload:

13


{"connId": "50d68a2b7bf23fc51f000001","channel": "#cats","nicks":{

"someone": "@","someoneelse": ""

}}

Fields:

connId: The ID of the IRC connectionchannel: The channel of this userlistnicks: dict of usernames and their privilege level on the channel

2.4 topic

Emitted when the server sends the channel topic on joining a channel, or when a user changes the topicon a channel.

Event Payload:

{"connId": "50d68a2b7bf23fc51f000001","channel": "#cats","topic": "omg cats!","nick": "somedude"

}

Fields:

connId: The ID of the IRC connectionchannel: The channel of this topictopic: The topic of the channelnick: Who set the topic

2.5 join

Emitted when a user joins a channel (including when the client itself joins a channel).

Event Payload:

{"connId": "50d68a2b7bf23fc51f000001","channel": "cats","nick": "thatcatguy"

}

Fields:

connId: The ID of the IRC connectionchannel: The channel that a user joinednick: The nick of the user that joined the channel

14 Chapter 2. Events


2.6 part

As per ‘join’ event but only emits for the subscribed channel.

Event Payload:

{"connId": "50d68a2b7bf23fc51f000001","channel": "cats","nick": "thatcatguy","reason": "off to the cat store"

}

Fields:

connId: The ID of the IRC connectionchannel: The channel that a user joinednick: The nick of the user that joined the channelreason: The reason for parting the channel

2.7 quit

Emitted when a user disconnects from the IRC, leaving the specified array of channels.

Event Payload:

{"connId": "50d68a2b7bf23fc51f000001","nick": "thatcatguy","reason": "too many cats""channels":

["#cats","#moarcats"

]}

Fields:

connId: The ID of the IRC connectionnick: The nick of the user that quitreason: The reason the user has quitchannels: Array of channels the user was in

2.8 kick

Emitted when a user is kicked from a channel.

Event Payload:

{"connId": "50d68a2b7bf23fc51f000001","channel": "#cats""nick": "verydesperate""by": "justheretomod"

2.6. part 15


"reason": "not as desperate as you’d think"}

Fields:

connId: The ID of the IRC connectionchannel: The channel the user was kicked fromnick: The nick of the user that was kickedby: Who kicked this userreason: Why the user was kicked

2.9 kill

Emitted when a user is killed from the IRC server. channels is an array of channels the killed user was inwhich are known to the client.

Event Payload:

{"connId": "50d68a2b7bf23fc51f000001","nick": "lollerskatesmcgee","reason": "i don’t like you","channels":

["#cats","#moarcats"

]}

Fields:

connId: The ID of the IRC connectionnick: The nick of the user that was killedreason: The reason the user was killedchannnels: Array of channels the user was killed from

2.10 message

Emitted when a message is sent to any channel.

Event Payload:

{"connId": "50d68a2b7bf23fc51f000001","from": "lollerskatesmcgee","to": "#bacon","text": "omg bacon! i’m you’re biggest fan"

}

Fields:

connId: The ID of the IRC connectionfrom: The nick of the user that sent the messageto: The target channel this message was sent to



text: The body of the message

2.11 notice

Emitted when a notice is sent. to can be either a nick (which is most likely this clients nick and means aprivate message), or a channel (which means a message to that channel). nick is either the senders nick ornull which means that the notice comes from the server.

Event Payload:

{"connId": "50d68a2b7bf23fc51f000001","nick": "freeipods","to": "omgme32","text": "yo dawg...i heard you like affordable and legitimate goods",

}

Fields:

connId: The ID of the IRC connectionnick: The nick of the user, channel name, or null (from server) that has sent this noticeto: Who the notice was sent totext: The text of the notice

2.12 nick

Emitted when a user changes nick along with the channels the user is in.

Event Payload:

{"connId": "50d68a2b7bf23fc51f000001","oldNick": "probablynotadude","newNick": "definitelynotadude","channels":

["#cats","#moarcats","#casual"

]}

Fields:

connId: The ID of the IRC connectionoldNick: The user’s old nicknewNick: The user’s new nickchannels: Array of channels the user is in (that we know of)

2.13 pm

As per ‘message’ event but only emits when the message is direct to the client.

2.11. notice 17


Event Payload:

{"connId": "50d68a2b7bf23fc51f000001","nick": "lolskrillex","text": "yo bro you hear my new album"

}

Fields:

connId: The ID of the IRC connectionnick: The nick of the user sending the PMtext: The body of the message

2.14 invite

Emitted when the client recieves an /invite.

Event Payload:

{"connId": "50d68a2b7bf23fc51f000001","channel": "#thebeach","from": "definitelynotadude"

}

Fields:

connId: The ID of the IRC connectionchannel: The channel this client has been invited tofrom: Who is sending the invite

2.15 +mode

Emitted when a mode is added to a user or channel. channel is the channel which the mode is being seton/in. by is the user setting the mode. mode is the single character mode indentifier. If the mode is beingset on a user, argument is the nick of the user. If the mode is being set on a channel, argument is theargument to the mode. If a channel mode doesn’t have any arguments, argument will be ‘undefined’.

Event Payload:

{"connId": "50d68a2b7bf23fc51f000001","channel": "#cats","by": "oneOPtoRULE","mode": "v","argument": "currentlyMUTE"

}

Fields:

connId: The ID of the IRC connectionchannel: The channel the event has occurred inby: Who has set the modemode: The mode being set



argument: As per description: nick, channel, or undefined

2.16 -mode

Emitted when a mode is removed from a user or channel. channel is the channel which the mode is beingset on/in. by is the user setting the mode. mode is the single character mode indentifier. If the mode isbeing set on a user, argument is the nick of the user. If the mode is being set on a channel, argument is theargument to the mode. If a channel mode doesn’t have any arguments, argument will be ‘undefined’.

Event Payload:

{"connId": "50d68a2b7bf23fc51f000001","channel": "#cats","by": "oneOPtoRULE","mode": "v","argument": "currentlyMUTE"

}

Fields:

connId: The ID of the IRC connectionchannel: The channel the event has occurred inby: Who has set the modemode: The mode being setargument: As per description: nick, channel, or undefined

2.17 whois

Emitted whenever the server finishes outputting a WHOIS response.

Event Payload:

{"connId": "50d68a2b7bf23fc51f000001","info":{

nick: "Ned",user: "martyn",host: "10.0.0.18",realname: "Unknown",channels: ["@#purpledishwashers", "#blah", "#mmmmbacon"],server: "*.dollyfish.net.nz",serverinfo: "The Dollyfish Underworld",operator: "is an IRC Operator"

}}

Fields:

connId: The ID of the IRC connectioninfo: Whois data being returned

2.16. -mode 19


2.18 error

Emitted when ever the server responds with an error-type message.

Event Payload:

{"connId": "50d68a2b7bf23fc51f000001","message": "Server Error: Not Enough Love"

}

Fields:

connId: The ID of the IRC connectionmessage: The raw message from the server

2.19 channels

Emitted when ever the server responds with an error-type message.

Event Payload:

{"channels": ["#cats", "#omgcats", "#soomanycats"]

}

Fields:

channels: Array of all channels that this IRC session is joined to

2.20 channel_details

Emitted when ever the server responds with channel details for a particular channel

Event Payload:

{"channel": "#cats","topic": "cats :: pretty cool, eh?","topic_by": "thatcatguy","modes": ["p"],"userlist": {"someguy": "vo", "someotherguy": "v"}

}

Fields:

channel: The channel that details are being returned fortopic: The topic of this channeltopic_by: Who set the topicmodes: The modes currently set on this channeluserlist: All of the users in this channel and their corresponding modes


CHAPTER

THREE

INDICES AND TABLES

• genindex

• modindex

• search

21

linkd api documentation - read the docs · · 2013-05-02linkd api documentation, release 0.1...

Documents