@clientcasa/sdk

v0.7.4

Published

3 days ago

Official TypeScript SDK for the [ClientCasa](https://www.clientcasa.com) REST API.

0High
0Medium
0Low

allandelmare

@clientcasa/sdk

Official TypeScript SDK for the ClientCasa REST API.

npm install @clientcasa/sdk
# or
pnpm add @clientcasa/sdk
# or
yarn add @clientcasa/sdk

Works in Node.js 18+, modern browsers, Edge runtimes, Cloudflare Workers, and Deno.

Quick start

Get an API key from Settings → API Keys in your dashboard, then:

import { ClientCasa } from '@clientcasa/sdk'

const cc = new ClientCasa()
const security = { apiKey: process.env.CLIENTCASA_API_KEY ?? '' }

// List clients
const result = await cc.clients.listClients(security, { pageSize: 25 })
for (const client of result.data) {
  console.log(client.name, client.status)
}

// Create a client
const created = await cc.clients.createClient(security, {
  name: 'Acme Inc.',
  status: 'active',
})

// Get one by ID
const fetched = await cc.clients.getClient(security, { id: created.id })

// Update
await cc.clients.updateClient(security, {
  id: created.id,
  clientUpdate: { notes: 'Updated via SDK' },
})

// Delete
await cc.clients.deleteClient(security, { id: created.id })

Errors are thrown — wrap calls in try/catch to handle them.

OAuth (third-party apps)

If you're building a third-party app that acts on behalf of a user, use the access token from your OAuth flow:

const security = { bearer: 'eyJhbGc...' }  // from /api/auth/oauth2/token
const result = await cc.clients.listClients(security, {})

See the OAuth Apps guide for the full authorization-code-with-PKCE flow.

Resources

The client exposes one accessor per v1 resource. Method names follow the verb-then-resource pattern (listClients, createInvoice, getPayout, etc.):

| Accessor | Methods | Notes | |---|---|---| | cc.clients | listClients, createClient, getClient, updateClient, deleteClient | | | cc.contacts | listContacts, createContact, getContact, updateContact, deleteContact | | | cc.projects | listProjects, createProject, getProject, updateProject, deleteProject | | | cc.invoices | listInvoices, createInvoice, getInvoice, updateInvoice, deleteInvoice | Status is payment-derived; only draft, sent, void writable | | cc.proposals | listProposals, createProposal, getProposal, updateProposal, deleteProposal | Tiptap content not editable via API | | cc.contracts | listContracts, createContract, getContract, updateContract, deleteContract | Create makes drafts only; signing is dashboard-managed | | cc.payments | listPayments, createPayment, getPayment, updatePayment | Immutable — no delete. Refunds are negative-amount entries with kind=refund | | cc.payouts | listPayouts, getPayout | Read-only — Stripe-managed | | cc.timeEntries | listTimeEntries, createTimeEntry, getTimeEntry, updateTimeEntry, deleteTimeEntry | | | cc.milestones | listMilestones, createMilestone, getMilestone, updateMilestone, deleteMilestone | Polymorphic parent (parentType: 'projects' \| 'proposals') | | cc.calendarEvents | listCalendarEvents, createCalendarEvent, getCalendarEvent, updateCalendarEvent, deleteCalendarEvent | Externally-synced events are read-only | | cc.inquiries | listInquiries, createInquiry, getInquiry, updateInquiry, deleteInquiry | Inquiries land in status: 'new'; converted set by the dashboard | | cc.transactions | listTransactions, createTransaction, getTransaction, updateTransaction, deleteTransaction | | | cc.catalogItems | listCatalogItems, createCatalogItem, getCatalogItem, updateCatalogItem, deleteCatalogItem | | | cc.webhooks | listWebhooks, createWebhook, getWebhook, updateWebhook, deleteWebhook | Secret is write-only |

Error handling

Methods throw typed errors on non-2xx responses. Each operation has its own named error class:

import { ClientCasa } from '@clientcasa/sdk'
import { APIError, HTTPClientErrors } from '@clientcasa/sdk/models/errors'

try {
  const result = await cc.clients.getClient(security, { id: 'bad-id' })
  console.log(result.name)
} catch (err) {
  if (err instanceof APIError) {
    console.error(err.statusCode)            // 404
    console.error(err.message)               // human-readable
    // Decoded error body if the response was JSON:
    // err.body has { error: { code, message, requestId, details? } }
  } else {
    throw err
  }
}

See docs/models/errors/ for per-operation error types.

Idempotency

Pass an Idempotency-Key header on write operations to safely retry:

import { randomUUID } from 'node:crypto'

await cc.invoices.createInvoice(
  security,
  {
    clientId: 'cli_...',
    issueDate: '2026-05-19',
    dueDate: '2026-06-18',
    lineItems: [{ description: 'Consult', quantity: 1, unitPrice: 500, taxable: false }],
  },
  { headers: { 'Idempotency-Key': randomUUID() } },
)

The same key replayed within 24h returns the cached response. See the Idempotency guide for the full pattern, including payments and refunds.

Configuration

import { ClientCasa } from '@clientcasa/sdk'

new ClientCasa({
  // Optional default API key — applied to every method that takes `security`.
  // Per-call security still overrides if both are set.
  apiKey: process.env.CLIENTCASA_API_KEY ?? '',
  // Override the production base URL (e.g., for staging or test envs)
  serverURL: 'https://www.clientcasa.com',
  // Override the underlying HTTP client (e.g., to inject middleware)
  httpClient: undefined,
  // Custom retry config (defaults are already sensible)
  retryConfig: undefined,
  // Per-call timeout in milliseconds
  timeoutMs: 30_000,
})

TypeScript

All DTOs are exported under the @clientcasa/sdk/models subpath:

import type { Client, InvoiceCreate, PaginationMeta } from '@clientcasa/sdk/models'

Per-operation request/response types live under @clientcasa/sdk/models/operations.

Contributing

This SDK is auto-generated from the ClientCasa OpenAPI spec by Speakeasy. Most changes belong upstream in the API, not here.

Found a bug or want a feature? Open an issue — include the SDK version, what you tried, and the unexpected behavior.
Want to suggest an SDK-specific improvement (ergonomics, retries, packaging)? Open an issue and we'll discuss before code.
Security issue? See SECURITY.md. Do not file a public issue.

Pull requests touching src/generated/ will be regenerated and overwritten — please don't edit generated code directly. See CONTRIBUTING.md for the full contributor guide.

Versioning

The SDK follows the API's v1 contract. Breaking changes go in a major version bump; new resources and new optional fields are minor versions.

License

MIT

Summary

ClientCasa API: REST API for ClientCasa — proposals, contracts, time tracking, expenses, invoicing, payments, and CRM for solo operators and small teams.

@clientcasa/sdk

SDK Installation

The SDK can be installed with either npm, pnpm, bun or yarn package managers.

NPM

npm add @clientcasa/sdk

PNPM

pnpm add @clientcasa/sdk

Bun

bun add @clientcasa/sdk

Yarn

yarn add @clientcasa/sdk

[!NOTE] This package is published as an ES Module (ESM) only. For applications using CommonJS, use await import("@clientcasa/sdk") to import and use this package.

Requirements

For supported JavaScript runtimes, please consult RUNTIMES.md.

SDK Example Usage

Example

import { ClientCasa } from "@clientcasa/sdk";

const clientCasa = new ClientCasa();

async function run() {
  const result = await clientCasa.clients.list({
    apiKey: process.env["CLIENTCASA_API_KEY"] ?? "",
  }, {});

  for await (const page of result) {
    console.log(page);
  }
}

run();

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

| Name | Type | Scheme | Environment Variable | | -------- | ------ | ------- | -------------------- | | apiKey | apiKey | API key | CLIENTCASA_API_KEY |

To authenticate with the API the apiKey parameter must be set when initializing the SDK client instance. For example:

Per-Operation Security Schemes

Some operations in this SDK require the security scheme to be specified at the request level. For example:

import { ClientCasa } from "@clientcasa/sdk";

const clientCasa = new ClientCasa();

async function run() {
  const result = await clientCasa.clients.list({}, {});

  for await (const page of result) {
    console.log(page);
  }
}

run();

Available Resources and Operations

CalendarEvents

list - List calendar events
create - Create a calendar event
get - Get a calendar event
delete - Delete a calendar event
update - Update a calendar event

CatalogItems

list - List catalog items
create - Create a catalog item
get - Get a catalog item
delete - Delete a catalog item
update - Update a catalog item

Clients

list - List clients
create - Create a client
get - Get a client
delete - Delete a client
update - Update a client

Contacts

list - List contacts
create - Create a contact
get - Get a contact
delete - Delete a contact
update - Update a contact

Contracts

list - List contracts
create - Create a draft contract
get - Get a contract
delete - Delete a contract (only drafts)
update - Update a contract (limited fields)

DocumentVersions

list - List document versions
get - Get a document version

EventDayVendors

list - List event day vendors
create - Add a vendor to an event day
get - Get an event day vendor
delete - Remove a vendor from an event day
update - Update an event day vendor

EventDays

list - List event days
create - Create an event day
get - Get an event day
delete - Delete an event day
update - Update an event day

FormSubmissions

list - List form submissions
get - Get a form submission (with answers)

Forms

list - List forms
get - Get a form

FormsAndAgreements

list - List proposals
get - Get a proposal

Inquiries

create - Submit an inquiry (capture a lead)

Invoices

list - List invoices
create - Create an invoice
get - Get an invoice
delete - Delete an invoice (only drafts)
update - Update an invoice (line items not editable in v1)

Milestones

list - List milestones
create - Create a milestone
get - Get a milestone
delete - Delete a milestone
update - Update a milestone

Payments

list - List payments
create - Record a manual payment
get - Get a payment
update - Update a payment (notes/reference only — payments are otherwise immutable)

Payouts

list - List payouts
get - Get a payout

Projects

list - List projects
create - Create a project
get - Get a project
delete - Delete a project
update - Update a project

Sales

list - List sales
get - Get a sale

TimeEntries

list - List time entries
create - Create a time entry
get - Get a time entry
delete - Delete a time entry
update - Update a time entry

TimelineItems

list - List timeline items
create - Create a timeline item
get - Get a timeline item
delete - Delete a timeline item
update - Update a timeline item

Transactions

list - List transactions
create - Create a transaction (expense or charge)
get - Get a transaction
delete - Delete a transaction
update - Update a transaction

Vendors

list - List vendors
create - Create a vendor
get - Get a vendor
delete - Delete a vendor
update - Update a vendor

Venues

list - List venues
create - Create a venue
get - Get a venue
delete - Delete a venue
update - Update a venue

Webhooks

list - List webhook subscriptions
create - Subscribe to events
get - Get a webhook
delete - Delete a webhook
update - Update a webhook

Standalone functions

All the methods listed above are available as standalone functions. These functions are ideal for use in applications running in the browser, serverless runtimes or other environments where application bundle size is a primary concern. When using a bundler to build your application, all unused functionality will be either excluded from the final bundle or tree-shaken away.

To read more about standalone functions, check FUNCTIONS.md.

calendarEventsCreate - Create a calendar event
calendarEventsDelete - Delete a calendar event
calendarEventsGet - Get a calendar event
calendarEventsList - List calendar events
calendarEventsUpdate - Update a calendar event
catalogItemsCreate - Create a catalog item
catalogItemsDelete - Delete a catalog item
catalogItemsGet - Get a catalog item
catalogItemsList - List catalog items
catalogItemsUpdate - Update a catalog item
clientsCreate - Create a client
clientsDelete - Delete a client
clientsGet - Get a client
clientsList - List clients
clientsUpdate - Update a client
contactsCreate - Create a contact
contactsDelete - Delete a contact
contactsGet - Get a contact
contactsList - List contacts
contactsUpdate - Update a contact
contractsCreate - Create a draft contract
contractsDelete - Delete a contract (only drafts)
contractsGet - Get a contract
contractsList - List contracts
contractsUpdate - Update a contract (limited fields)
documentVersionsGet - Get a document version
documentVersionsList - List document versions
eventDaysCreate - Create an event day
eventDaysDelete - Delete an event day
eventDaysGet - Get an event day
eventDaysList - List event days
eventDaysUpdate - Update an event day
eventDayVendorsCreate - Add a vendor to an event day
eventDayVendorsDelete - Remove a vendor from an event day
eventDayVendorsGet - Get an event day vendor
eventDayVendorsList - List event day vendors
eventDayVendorsUpdate - Update an event day vendor
formsAndAgreementsGet - Get a proposal
formsAndAgreementsList - List proposals
formsGet - Get a form
formsList - List forms
formSubmissionsGet - Get a form submission (with answers)
formSubmissionsList - List form submissions
inquiriesCreate - Submit an inquiry (capture a lead)
invoicesCreate - Create an invoice
invoicesDelete - Delete an invoice (only drafts)
invoicesGet - Get an invoice
invoicesList - List invoices
invoicesUpdate - Update an invoice (line items not editable in v1)
milestonesCreate - Create a milestone
milestonesDelete - Delete a milestone
milestonesGet - Get a milestone
milestonesList - List milestones
milestonesUpdate - Update a milestone
paymentsCreate - Record a manual payment
paymentsGet - Get a payment
paymentsList - List payments
paymentsUpdate - Update a payment (notes/reference only — payments are otherwise immutable)
payoutsGet - Get a payout
payoutsList - List payouts
projectsCreate - Create a project
projectsDelete - Delete a project
projectsGet - Get a project
projectsList - List projects
projectsUpdate - Update a project
salesGet - Get a sale
salesList - List sales
timeEntriesCreate - Create a time entry
timeEntriesDelete - Delete a time entry
timeEntriesGet - Get a time entry
timeEntriesList - List time entries
timeEntriesUpdate - Update a time entry
timelineItemsCreate - Create a timeline item
timelineItemsDelete - Delete a timeline item
timelineItemsGet - Get a timeline item
timelineItemsList - List timeline items
timelineItemsUpdate - Update a timeline item
transactionsCreate - Create a transaction (expense or charge)
transactionsDelete - Delete a transaction
transactionsGet - Get a transaction
transactionsList - List transactions
transactionsUpdate - Update a transaction
vendorsCreate - Create a vendor
vendorsDelete - Delete a vendor
vendorsGet - Get a vendor
vendorsList - List vendors
vendorsUpdate - Update a vendor
venuesCreate - Create a venue
venuesDelete - Delete a venue
venuesGet - Get a venue
venuesList - List venues
venuesUpdate - Update a venue
webhooksCreate - Subscribe to events
webhooksDelete - Delete a webhook
webhooksGet - Get a webhook
webhooksList - List webhook subscriptions
webhooksUpdate - Update a webhook

Pagination

Some of the endpoints in this SDK support pagination. To use pagination, you make your SDK calls as usual, but the returned response object will also be an async iterable that can be consumed using the for await...of syntax.

Here's an example of one such pagination call:

import { ClientCasa } from "@clientcasa/sdk";

const clientCasa = new ClientCasa();

async function run() {
  const result = await clientCasa.clients.list({
    apiKey: process.env["CLIENTCASA_API_KEY"] ?? "",
  }, {});

  for await (const page of result) {
    console.log(page);
  }
}

run();

Retries

Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a retryConfig object to the call:

import { ClientCasa } from "@clientcasa/sdk";

const clientCasa = new ClientCasa();

async function run() {
  const result = await clientCasa.clients.list(
    {
      apiKey: process.env["CLIENTCASA_API_KEY"] ?? "",
    },
    {},
    {
      retries: {
        strategy: "backoff",
        backoff: {
          initialInterval: 1,
          maxInterval: 50,
          exponent: 1.1,
          maxElapsedTime: 100,
        },
        retryConnectionErrors: false,
      },
    },
  );

  for await (const page of result) {
    console.log(page);
  }
}

run();

If you'd like to override the default retry strategy for all operations that support retries, you can provide a retryConfig at SDK initialization:

import { ClientCasa } from "@clientcasa/sdk";

const clientCasa = new ClientCasa({
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
});

async function run() {
  const result = await clientCasa.clients.list({
    apiKey: process.env["CLIENTCASA_API_KEY"] ?? "",
  }, {});

  for await (const page of result) {
    console.log(page);
  }
}

run();

Error Handling

ClientCasaError is the base class for all HTTP error responses. It has the following properties:

| Property | Type | Description | | ------------------- | ---------- | --------------------------------------------------------------------------------------- | | error.message | string | Error message | | error.statusCode | number | HTTP response status code eg 404 | | error.headers | Headers | HTTP response headers | | error.body | string | HTTP body. Can be empty string if no body is returned. | | error.rawResponse | Response | Raw HTTP response | | error.data$ | | Optional. Some errors may contain structured data. See Error Classes. |

Example

import { ClientCasa } from "@clientcasa/sdk";
import * as errors from "@clientcasa/sdk/models/errors";

const clientCasa = new ClientCasa();

async function run() {
  try {
    const result = await clientCasa.clients.list({
      apiKey: process.env["CLIENTCASA_API_KEY"] ?? "",
    }, {});

    for await (const page of result) {
      console.log(page);
    }
  } catch (error) {
    // The base class for HTTP error responses
    if (error instanceof errors.ClientCasaError) {
      console.log(error.message);
      console.log(error.statusCode);
      console.log(error.body);
      console.log(error.headers);

      // Depending on the method different errors may be thrown
      if (error instanceof errors.ApiError) {
        console.log(error.data$.error); // models.ErrorT
      }
    }
  }
}

run();

Error Classes

Primary errors:

ClientCasaError: The base class for HTTP error responses.
- ApiError: Generic error.

Network errors:

ConnectionError: HTTP client was unable to make a request to a server.
RequestTimeoutError: HTTP request timed out due to an AbortSignal signal.
RequestAbortedError: HTTP request was aborted by the client.
InvalidRequestError: Any input used to create a request is invalid.
UnexpectedClientError: Unrecognised or unexpected error.

Inherit from ClientCasaError:

ResponseValidationError: Type mismatch between the data returned from the server and the structure expected by the SDK. See error.rawValue for the raw value and error.pretty() for a nicely formatted multi-line string.

Server Selection

Override Server URL Per-Client

The default server can be overridden globally by passing a URL to the serverURL: string optional parameter when initializing the SDK client instance. For example:

import { ClientCasa } from "@clientcasa/sdk";

const clientCasa = new ClientCasa({
  serverURL: "https://www.clientcasa.com",
});

async function run() {
  const result = await clientCasa.clients.list({
    apiKey: process.env["CLIENTCASA_API_KEY"] ?? "",
  }, {});

  for await (const page of result) {
    console.log(page);
  }
}

run();

Custom HTTP Client

The TypeScript SDK makes API calls using an HTTPClient that wraps the native Fetch API. This client is a thin wrapper around fetch and provides the ability to attach hooks around the request lifecycle that can be used to modify the request or handle errors and response.

The HTTPClient constructor takes an optional fetcher argument that can be used to integrate a third-party HTTP client or when writing tests to mock out the HTTP client and feed in fixtures.

The following example shows how to:

route requests through a proxy server using undici's ProxyAgent
use the "beforeRequest" hook to add a custom header and a timeout to requests
use the "requestError" hook to log errors

import { ClientCasa } from "@clientcasa/sdk";
import { ProxyAgent } from "undici";
import { HTTPClient } from "@clientcasa/sdk/lib/http";

const dispatcher = new ProxyAgent("http://proxy.example.com:8080");

const httpClient = new HTTPClient({
  // 'fetcher' takes a function that has the same signature as native 'fetch'.
  fetcher: (input, init) =>
    // 'dispatcher' is specific to undici and not part of the standard Fetch API.
    fetch(input, { ...init, dispatcher } as RequestInit),
});

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(5000)
  });

  nextRequest.headers.set("x-custom-header", "custom value");

  return nextRequest;
});

httpClient.addHook("requestError", (error, request) => {
  console.group("Request Error");
  console.log("Reason:", `${error}`);
  console.log("Endpoint:", `${request.method} ${request.url}`);
  console.groupEnd();
});

const sdk = new ClientCasa({ httpClient: httpClient });

Debugging

You can setup your SDK to emit debug logs for SDK requests and responses.

You can pass a logger that matches console's interface as an SDK option.

[!WARNING] Beware that debug logging will reveal secrets, like API tokens in headers, in log messages printed to a console or files. It's recommended to use this feature only during local development and not in production.

import { ClientCasa } from "@clientcasa/sdk";

const sdk = new ClientCasa({ debugLogger: console });

You can also enable a default debug logger by setting an environment variable CLIENTCASA_DEBUG to true.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@clientcasa/sdk

Quick start

OAuth (third-party apps)

Resources

Error handling

Idempotency

Configuration

TypeScript

Contributing

Versioning

License

Summary

Table of Contents

SDK Installation

NPM

PNPM

Bun

Yarn

Requirements

SDK Example Usage

Example

Authentication

Per-Client Security Schemes

Per-Operation Security Schemes

Available Resources and Operations

Standalone functions

Pagination

Retries

Error Handling

Example

Error Classes

Server Selection

Override Server URL Per-Client

Custom HTTP Client

Debugging