zendesk_api 0.1.11 → 0.2.1

data/lib/zendesk_api/server/base.rb

@@ -0,0 +1,119 @@
+require 'sinatra/base'
+require 'sinatra/content_for'
+require 'sinatra/reloader'
+
+require 'compass'
+require 'haml'
+
+require 'coderay'
+require 'coderay_bash'
+
+require 'json'
+require 'redcarpet'
+
+require 'digest/md5'
+
+require 'mongoid'
+
+require 'zendesk_api/server/models/user_request'
+Mongoid.load!(File.join(File.dirname(__FILE__), '..', '..', '..', 'config', 'mongoid.yml'))
+
+module ZendeskAPI
+  module Server
+    require 'zendesk_api/server/helper'
+    require 'zendesk_api/server/html_renderer'
+
+    class App < Sinatra::Base
+      enable :sessions
+
+      helpers Sinatra::ContentFor
+      helpers Helper
+
+      configure do
+        set :public_folder, File.join(File.dirname(__FILE__), 'public')
+        set :views, File.join(File.dirname(__FILE__), 'templates')
+
+        set :documentation_dir, File.join(File.dirname(__FILE__), "docs")
+
+        documentation = Dir.glob(File.join(settings.documentation_dir, "*.md")).inject({}) do |docs, entry|
+          body = HtmlRenderer.render(File.open(entry, &:read))
+          headers = HtmlRenderer.markdown.renderer.headers.dup
+
+          HtmlRenderer.markdown.renderer.headers.clear
+
+          docs.merge(File.basename(entry, ".md") => { :body => body, :headers => headers })
+        end
+
+        set :documentation, documentation
+        set :help, documentation["introduction"][:body]
+
+        autocomplete = settings.documentation.inject([]) do |accum, (resource, content)|
+          accum.push(resource)
+          accum.concat(content[:headers].map {|header| "#{resource}##{header}"})
+          accum
+        end + ["help"]
+
+        set :autocomplete, autocomplete
+      end
+
+      configure :development do
+        register Sinatra::Reloader
+      end
+
+      get '/' do
+        haml :index, :format => :html5
+      end
+
+      get '/:object_id' do
+        begin
+          @user_request = UserRequest.where(:_id => Moped::BSON::ObjectId(params[:object_id])).first
+        rescue Moped::Errors::InvalidObjectId; end
+
+        if @user_request
+          params["url"] = @user_request.url
+          @path = @user_request.path
+
+          @method = @user_request.method
+          @json = @user_request.json
+          @url_params = @user_request.url_params
+
+          set_request(@user_request.request) unless @user_request.request.empty?
+          set_response(@user_request.response) unless @user_request.response.empty?
+        end
+
+        haml :index, :format => :html5
+      end
+
+      post '/search' do
+        if md = settings.documentation[params[:query]]
+          md[:body]
+        else
+          settings.help
+        end
+      end
+
+      post '/' do
+        @method = (params.delete("method") || "get").downcase.to_sym
+        @path = coerce_path(params.delete("url"))
+        @json = params.delete("json")
+        @url_params = (params.delete("params") || {}).delete_if do |param|
+          !param["name"] || !param["value"] || (param["name"].empty? && param["value"].empty?)
+        end
+
+        execute_request unless @error
+
+        @user_request = UserRequest.create(
+          :method => @method,
+          :url => params["url"],
+          :path => @path,
+          :json => @json,
+          :url_params => @url_params,
+          :request => @user_request_hash,
+          :response => @user_response_hash
+        ) unless @error
+
+        haml :index, :format => :html5
+      end
+    end
+  end
+end

data/lib/zendesk_api/server/docs/account_settings.md

@@ -0,0 +1,145 @@
+## Account Settings
+
+### JSON Format
+Account Settings are read-only. They contain settings for the various aspects of an Account.
+
+### Branding
+
+| Name                               | Type    | Comment
+| ---------------------------------- | ------- | -------
+| header_color                       | string  | HEX of the header color
+| page_background_color              | string  | HEX of the page background color
+| tab_background_color               | string  | HEX of tab background color
+| text_color                         | string  | HEX of the text color, usually matched to contrast well with `header_color`
+
+### Apps
+
+| Name                               | Type    | Comment
+| ---------------------------------- | ------- | -------
+| use                                | boolean | The Account can use apps
+| create_private                     | boolean | The Account can create private apps
+| create_public                      | boolean | The Account can create public apps
+
+### Tickets
+
+| Name                               | Type    | Comment
+| ---------------------------------- | ------- | -------
+| comments_public_by_default         | boolean | Comments from agents are public by default
+| list_newest_comments_first         | boolean | When viewing a ticket, show the newest comments and events first
+| collaboration                      | boolean | CCs may be added to a ticket
+| private_attachments                | boolean | Users must login to acesss attachments
+| agent_collision                    | boolean | Clients should provide an indicator when a ticket is being viewed by another agent
+| list_empty_views                   | boolean | Clients should display Views with no matching Tickets in menus
+| maximum_personal_views_to_list     | number  | Maximum number of personal Views clients should display in menus
+| tagging                            | boolean | Tickets may be tagged
+
+### Chat
+
+| Name                               | Type    | Comment
+| ---------------------------------- | ------- | -------
+| enabled                            | boolean | Chat is enabled
+| maximum_requests                   | number  | The maximum number of chat requests an agent may handle at one time
+| welcome_message                    | string  | The message automatically sent to end-users when they begin chatting with an agent
+
+### Twitter
+
+| Name                               | Type    | Comment
+| ---------------------------------- | ------- | -------
+| shorten_url                        | string | Possible values: 'always', 'optional', 'never'
+
+### Voice
+
+| Name                               | Type    | Comment
+| ---------------------------------- | ------- | -------
+| enabled                            | boolean | Voice is enabled
+| maintenance                        | boolean |
+| logging                            | boolean |
+
+### Users
+
+| Name                               | Type    | Comment
+| ---------------------------------- | ------- | -------
+| tagging                            | boolean | Users may be tagged
+
+### Screencast
+
+| Name                               | Type    | Comment
+| ---------------------------------- | ------- | -------
+| enabled_for_tickets                | boolean | Account can record Screencasts on Tickets.
+| host                               | string  | The Screenr domain used when recording and playing Screencasts.
+| tickets_recorder_id                | string  | The Screenr Recorder id used when recording Screencasts.
+
+
+#### Example
+
+```js
+"settings": {
+  "branding": {
+    "header_color": "1A00C3",
+    "page_background_color": "333333",
+    "tab_background_color": "3915A2",
+    "text_color": "FFFFFF"
+  },
+  "apps":{
+    "use":            true,
+    "create_private": false,
+    "create_public":  true
+  },
+  "tickets": {
+    "comments_public_by_default":     true,
+    "list_newest_comments_first":     true,
+    "collaboration":                  true,
+    "private_attachments":            true,
+    "agent_collision":                true
+    "list_empty_views":               true,
+    "maximum_personal_views_to_list": 12,
+    "tagging":                        true
+  },
+  "chat": {
+    "maximum_request_count": 5,
+    "welcome_message":       "Hello, how may I help you?",
+    "enabled":               true
+  },
+  "voice": {
+    "enabled":     true,
+    "maintenance": false,
+    "logging":     true
+  },
+  "twitter": {
+    "shorten_url":"optional"
+  },
+  "users": {
+    "tagging":true
+  }
+}
+```
+
+### Show Settings
+`GET /api/v2/account/settings.json`
+
+This shows the settings that are available for the account.
+
+#### Allowed For:
+
+ * Agents
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/account/settings.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+"settings": {
+  "apps": {.. },
+  "tickets": { ...  },
+  "chat": { ... },
+  "twitter": { ... },
+  "users": { ... }
+}
+```

data/lib/zendesk_api/server/docs/activity_stream.md

@@ -0,0 +1,121 @@
+## Activity Stream
+
+The **activity stream** is a per agent event stream. It will give access to the most recent events that relate to the agent polling the API.
+
+### JSON Format
+Ticket activity events are represented as JSON objects which have the following keys:
+
+| Name             | Type                   | Read-only | Mandatory | Comment
+| ---------------- | ---------------------- | --------- | --------- | -------
+| id               | integer                | yes       | no        | Automatically assigned upon creation
+| url              | string                 | yes       | no        | The API url of this activity
+| title            | string                 | yes       | yes       | Description of this activity
+| verb             | string                 | yes       | yes       | Identifies the type of the activity
+| user             | [User](users.md)       | yes       | yes       | The user this activity pertains to
+| actor            | [User](users.md)       | yes       | yes       | The actor causing the creation of the activity
+| created_at       | date                   | yes       | no        | When this record was created
+| updated_at       | date                   | yes       | no        | When this record last got updated
+| object           | object                 | yes       | no        | The content of this activity. Can be a ticket, comment, or change.
+| target           | object                 | yes       | no        | The target of this activity, a ticket.
+
+#### Example
+```js
+{
+  "id":          35,
+  "url":         "https://company.zendesk.com/api/v2/activities/35.json",
+  "verb":        "tickets.assignment",
+  "title":       "John Hopeful assigned ticket #123 to you",
+  "user":        { ... },
+  "actor":       { ... },
+  "created_at":  "2012-03-05T10:38:52Z",
+  "updated_at":  "2012-03-05T10:38:52Z"
+}
+```
+
+### List Activities
+`GET /api/v2/activities.json`
+
+#### Allowed For:
+
+ * Agents
+
+Lists activities pertaining to the user performing the request.
+
+#### Request Parameters
+
+You can pass an optional `since` parameter which designates a timestamp offset, and the API
+will only return activities happening after that offset. The format of the `since` parameter
+must be in UTC on ISO8601 form `%Y-%m-%dT%H:%M:%SZ`, e.g. `2012-04-03T16:02:46Z`
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/activities.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "activities": [
+    {
+      "id":          35,
+      "url":         "https://company.zendesk.com/api/v2/activities/35.json",
+      "verb":        "tickets.assignment",
+      "title":       "John Hopeful assigned ticket #123 to you",
+      "user":        { ... },
+      "actor":       { ... },
+      "created_at":  "2012-03-05T10:38:52Z",
+      "updated_at":  "2012-03-05T10:38:52Z"
+    },
+    {
+      "id":          45,
+      "url":         "https://company.zendesk.com/api/v2/activities/45.json",
+      "verb":        "tickets.comment",
+      "title":       "John Hopeful commented in ticket #44",
+      "user":        { ... },
+      "actor":       { ... },
+      "created_at":  "2012-03-05T11:32:44Z",
+      "updated_at":  "2012-03-05T11:32:44Z"
+    }
+  ]
+}
+```
+
+### Show Activity
+`GET /api/v2/activities/{id}.json`
+
+#### Allowed For:
+
+ * Agent
+
+Only provides access to an activities pertaining to the agent executing the request
+
+#### Using curl
+
+```bash
+curl https://{subdomain}.zendesk.com/api/v2/activities/{id}.json \
+  -v -u {email_address}:{password}
+```
+
+#### Example Response
+
+```http
+Status: 200 OK
+
+{
+  "activity": {
+    "id":          45,
+    "url":         "https://company.zendesk.com/api/v2/activities/45.json",
+    "verb":        "tickets.comment",
+    "title":       "John Hopeful commented in ticket #44",
+    "user":        { ... },
+    "actor":       { ... },
+    "created_at":  "2012-03-05T11:32:44Z",
+    "updated_at":  "2012-03-05T11:32:44Z"
+  }
+}
+```

data/lib/zendesk_api/server/docs/attachments.md

@@ -0,0 +1,73 @@
+## Attachments
+
+### JSON Format
+Attachments are represented as JSON objects with the following keys:
+
+| Name         | Type             | Read-only | Comment
+| ------------ | ---------------- | --------- | -------
+| id           | integer          | yes       | Automatically assigned when created
+| file_name    | string           | yes       | The name of the image file
+| content_url  | string           | yes       | A full URL where the attachment image file can be downloaded
+| content_type | string           | yes       | The content type of the image. Example value: `image/png`
+| size         | integer          | yes       | The size of the image file in bytes
+| thumbnails   | array            | yes       | An array of [Photo](#attachments) objects. Note that thumbnails do not have thumbnails.
+
+#### Example
+```js
+{
+  "id":           928374,
+  "file_name":    "my_funny_profile_pic.png",
+  "content_url":  "https://company.zendesk.com/attachments/my_funny_profile_pic.png",
+  "content_type": "image/png",
+  "size":         166144,
+  "thumbnails": [
+    {
+      "id":           928375,
+      "file_name":    "my_funny_profile_pic_thumb.png",
+      "content_url":  "https://company.zendesk.com/attachments/my_funny_profile_pic_thumb.png",
+      "content_type": "image/png",
+      "size":         58298
+    }
+  ]
+}
+```
+
+### Uploading files
+`POST /api/v2/uploads.json`
+
+Adding multiple attachments to the same upload is handled by splitting requests and
+passing the token received from the first request to each subsequent one.
+
+#### Allowed For
+
+ * End Users
+
+#### Using curl
+
+```bash
+ curl -u username:password -H "Content-Type: application/binary" \
+   --data-binary @file.dat -X POST \
+   "https://helpdesk.zendesk.com/api/v2/uploads.json?filename=myfile.dat&token={optional_token}"
+```
+
+#### Example Response
+
+```http
+Status: 201 Created
+
+{
+  "upload": {
+    "token": "6bk3gql82em5nmf",
+    "attachments": [
+      {
+        "id":           498483,
+        "name":         "crash.log",
+        "content_url":  "https://company.zendesk.com/attachments/crash.log",
+        "content_type": "text/plain",
+        "size":         2532,
+        "thumbnails":   []
+      }
+    ]
+  }
+}
+```