Basecamp
A nodejs module that wraps the Basecamp json api
Install / Use
/learn @mark-hahn/BasecampREADME
Basecamp
A nodejs module that wraps the Basecamp JSON api.
The Basecamp github project can be found here.
Features
- Supports new Basecamp JSON api (not old xml)
- Built-in oauth2 support
- Tools to link app to Basecamp account by visiting 37signals website
- Supports all 57 api requests (GET, POST, and PUT)
- Terminology, params, and command ops match api documentation
- Data can be objects, streams, or files
- Supports simultaneous multiple accounts
Status Alpha
It is complete and currently usable, but it has not been used in production yet and there are no unit tests. Many commands (those relating to accounts, projects, messages, and comments) have been verified to work ...
- get_projects
- get_projects_archived
- create_project
- create_attachment
- get_project
- get_accesses
- get_topics
- get_message
- create_message
- create_comment
The rest of the commands are expected to work. A command table was translated directly from the API docs and the commands that have been verified to work use that table.
TODO ...
- Tests
- Add coding examples to this readme
- Convenience functions for common commands
- Support express/connect for linking accounts callback
I could use some help. Tests will be hard since we can't easily mock the Basecamp api. I don't know express so someone else is going to have to add that.
Installation
npm install basecamp
Usage
The Basecamp wrapper module interface follows the Basecamp api documentation closely. Refer to the api document for help understanding the commands.
Client Class
client = new Basecamp.Client(client_id, client_secret, redirect_uri, userAgent);
Client represents your client application. This usually only has one instance (singleton).
client_id is the id given to you when registering your Basecamp application.
client_secret is the secret given to you when registering your Basecamp application.
redirect_uri is a return address to your app server. You use this to send your user to the Basecamp account to link their Basecamp acount to your application. It must exactly match what you specified during app registration.
userAgent is sent on every request. It is just a comment like "Your name (yourWebsite.com)". It is not connected to the registration of your app.
Client Method authNewUrl
authNewUrl = client.getAuthNewUrl(state);
Returns the url that your app's web page should use when taking the user to the Basecamp website to link their account with your app. Since this module runs in the server the url will need to be sent to the client. Usually this would be through an ajax request but could be sent with the html page in some situations.
Hint: This url could actually be a constant string in your web page. You would have to figure out that URL yourself. However, using the getAuthNewUrl method will guarantee the url is correct in future releases.
state is an arbitrary javascript object that will be serialized and added to this url. It will be returned to you when the Basecamp server issues the callback request to your server (see the authNewCallback method below). If the object has the property href, as in state.href, then the authNewCallback method below will redirect the user to this href. Usually you would provide a user id in the state object so you know what user is responsible for the Basecamp callback.
Client Method authNewCallback
client.authNewCallback(request, response, callback);
Your app server should route an incoming request for the redirect_uri specified above to this method. The request and response params are the ones supplied by the node http.createServer callback.
The callback signature is (error, userInfo). error is a standard error param from a node callback.
userInfo is an object that you should store for future use. Usually this would be stored in a db record for the user. Some of it's data will be needed for future method calls.
If you specifed a state param in the getAuthNewUrl method, then the state object will be available as userInfo.state.
The userinfo also contains a Basecamp user object in userInfo.identity and an array of account objects in userInfo.accounts. They represent all accounts the user has access to. Usually you would ask the user what account they want to interact with by presenting them a list of these accounts to choose from.
The return value of this method should be ignored.
Account Class
new basecamp.Account(client, accountId, refresh_token, callback);
Account represents a Basecamp account. Multiple instances for different accounts may exist at once.
client is an instance of the Client class.
accountId is the Basecamp id for the account. An array of all accounts with their ids is provided in the userInfo object returned by the authNewCallback callback (see above). An example of accountId would be userInfo.accounts[index].id.
refresh_token is also taken from the userInfo object returned by the authNewCallback callback. It is available as userInfo.refresh_token.
The callback signature is (error, account). error is a standard error param from a node callback and account is the instance of the class Account that has just been created.
The return value of this method should be ignored. You might notice that this is unusual for a class constructor.
There is only one method, req. It is the same method for Account, Project, Calendar, and Person classes and is documented in the "req method" section below.
The valid commands (ops) for an Account are listed here. They are in the order they appear in the api docs.
- get_attachments
- create_attachment
- get_calendars
- create_calendar
- get_documents
- get_global_events
- get_people
- get_person_me
- get_projects
- get_projects_archived
- create_project
- get_todolists_all
- get_todolists_all_completed
- get_topics_all
Project Class
new basecamp.Project(account, projectId);
Project represents a single project in a Basecamp account.
account is an instance of the Account class.
projectId is the Basecamp id for the project. Usually you would obtain the project id by using the "get_projects" command.
There is only one method, req. It is the same method for Account, Project, Calendar, and Person classes and is documented in the "req method" section below.
Valid commands (ops) for a Project are listed here. They are in the order they appear in the api docs. Note that all Account commands can also be used on Projects.
- get_accesses
- grant_access
- revoke_access
- get_attachments
- get_calendar_events
- get_calendar_events_past
- get_calendar_event
- create_calendar_event
- update_calendar_event
- delete_calendar_event
- create_comment
- delete_comment
- get_documents
- get_document
- create_document
- update_document
- delete_document
- get_project_events
- get_message
- create_message
- update_message
- delete_message
- get_project
- update_project
- delete_project
- get_todolists
- get_todolists_completed
- get_todolist
- create_todolist
- update_todolist
- delete_todolist
- get_todo
- create_todo
- update_todo
- delete_todo
- get_topics
- create_uploads
- get_upload
Calendar Class
new basecamp.Calendar(account, calendarId);
Calendar represents a single calendar in a Basecamp account.
account is an instance of the Account class.
calendarId is the Basecamp id for the calendar. Usually you would obtain the calendar id by using the "get_calendars" command.
There is only one method, req. It is the same method for Account, Project, Calendar, and Person classes and is documented in the "req method" section below.
Valid commands (ops) for a Calendar are listed here. They are in the order they appear in the api docs. Note that all Account commands can also be used on Calendars.
- get_accesses
- grant_access
- revoke_access
- get_calendar_events
- get_calendar_events_past
- get_calendar_event
- create_calendar_event
- update_calendar_even
