Class: Woods::Unblocked::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/woods/unblocked/client.rb

Overview

REST client for the Unblocked API v1.

Handles document and collection CRUD with rate limiting, retries, and error handling. Uses Net::HTTP for zero external dependencies.

Examples:

client = Client.new(api_token: "ubk_...")
client.put_document(
  collection_id: "uuid",
  title: "Order (model)",
  body: "# Order\n...",
  uri: "https://github.com/org/repo/blob/main/app/models/order.rb"
)

Constant Summary collapse

BASE_URL = 
'https://getunblocked.com/api/v1'
MAX_RETRIES = 
3
DEFAULT_TIMEOUT = 
30

Instance Method Summary collapse

Constructor Details

#initialize(api_token:, rate_limiter: RateLimiter.new) ⇒ Client

Returns a new instance of Client.

Parameters:

  • api_token (String) —

    Unblocked API token (Personal or Team)

  • rate_limiter (RateLimiter) (defaults to: RateLimiter.new) —

    Rate limiter instance

Raises:

  • (ArgumentError) —

    if api_token is nil or empty



32
33
34
35
36
37
 
# File 'lib/woods/unblocked/client.rb', line 32

def initialize(api_token:, rate_limiter: RateLimiter.new)
  raise ArgumentError, 'api_token is required' if api_token.nil? || api_token.to_s.strip.empty?

  @api_token = api_token
  @rate_limiter = rate_limiter
end

Instance Method Details

#create_collection(name:, description:, icon_url: nil) ⇒ Hash

Create a new collection.

Parameters:

  • name (String) —

    Collection name (1-32 chars)

  • description (String) —

    Collection description (1-4096 chars)

  • icon_url (String, nil) (defaults to: nil) —

    Optional icon URL

Returns:

  • (Hash) —

    { “id” => “collection-uuid”, “name” => “…”, … }



65
66
67
68
69
 
# File 'lib/woods/unblocked/client.rb', line 65

def create_collection(name:, description:, icon_url: nil)
  body = { name: name, description: description }
  body[:iconUrl] = icon_url if icon_url
  request(:post, 'collections', body)
end

#delete_document(document_id:) ⇒ Hash

Delete a document by ID.

Parameters:

  • document_id (String) —

    Document UUID

Returns:

  • (Hash) —

    API response



83
84
85
 
# File 'lib/woods/unblocked/client.rb', line 83

def delete_document(document_id:)
  request(:delete, "documents/#{document_id}")
end

#list_collections ⇒ Array<Hash>

List all collections.

Returns:

  • (Array<Hash>) —

    Collection objects



74
75
76
77
 
# File 'lib/woods/unblocked/client.rb', line 74

def list_collections
  result = request(:get, 'collections')
  result['items'] || result['data'] || [result].flatten.compact
end

#put_document(collection_id:, title:, body:, uri:) ⇒ Hash

Create or update a document (upsert by URI).

Documents are unique by ‘uri` across the organization. If a document with the given URI exists, it is updated; otherwise it is created. Documents become available for queries within ~1 minute.

Parameters:

  • collection_id (String) —

    Target collection UUID

  • title (String) —

    Document title (plain text)

  • body (String) —

    Document body (Markdown preferred)

  • uri (String) —

    Source URL (used as unique identifier and citation link)

Returns:

  • (Hash) —

    { “id” => “document-uuid” }



50
51
52
53
54
55
56
57
 
# File 'lib/woods/unblocked/client.rb', line 50

def put_document(collection_id:, title:, body:, uri:)
  request(:put, 'documents', {
            collectionId: collection_id,
            title: title,
            body: body,
            uri: uri
          })
end