Changelog

The ClientCasa API follows semantic versioning. Breaking changes are reserved for major version bumps (v1 → v2). Within v1, we add new optional fields and new endpoints without breaking existing integrations.

For the TypeScript SDK changelog (per-version codegen diffs), see the @clientcasa/sdk GitHub Releases.

Unreleased

Changes that have landed on main and will ship in the next release.

Added

• Document Versions — a new read-only resource (scope document-versions:read): the audit trail of issued versions across smart-files, invoices, and standalone contracts. Exposes version metadata, lifecycle timestamps, and lineage ids — never the frozen document content or client access tokens. GET /v1/document-versions, GET /v1/document-versions/{id} (issued versions only).
• Forms — a new read-only resource (scope forms:read): your inquiry and questionnaire form definitions (kind, name, slug, enabled, isDefault). Built in the dashboard designer, so read-only. GET /v1/forms, GET /v1/forms/{id}.
• Form Submissions — a new read-only resource (scope form-submissions:read): the submitted answers to your forms, with normalized responses. GET /v1/form-submissions, GET /v1/form-submissions/{id}.
• Client Documents — a new read-only resource (scope client-documents:read): the composer-built proposals and smart-files clients view, sign, and pay. Exposes kind, title, status, the linked contact/client/project, and conversion lineage (engagementProjectId, quoteConvertedAt). Templates are excluded. GET /v1/client-documents, GET /v1/client-documents/{id}.
• Clients — added taxSettings and invoiceRemindersEnabled (read + write), plus read-only recurringBilling ({ status, nextBillingDate }) and sourceSubmissionId.
• Invoices — added read-only supersedesInvoice (void→reissue lineage) and a ?supersedesInvoice={id} list filter for the forward link.

All additive — existing integrations are unaffected. Regenerate the SDK to pick up the new fields and resource.

2026-05-19 — v1.0.0 (initial release)

The public v1 API ships with 13 resources. Leads are not a separate resource — a lead is a client at an early lifecycle stage, fetched via /v1/clients?status=new|contacted|qualified.

Resources

• Clients — list/create/get/update/delete (clients:read, clients:write)
• Contacts — list/create/get/update/delete (contacts:read, contacts:write)
• Projects — list/create/get/update/delete (projects:read, projects:write)
• Invoices — list/create/get/update/delete (invoices:read, invoices:write). Status is payment-derived. Only draft, sent, void writable via the API (paid/partial/overdue are system-managed).
• Contracts — list/create/get/update/delete (contracts:read, contracts:write). Create produces drafts only. Signing flow + Tiptap content are dashboard-managed.
• Payments — list/create/get/update (payments:read, payments:write). Immutable after creation. No DELETE — refunds are negative-amount entries with kind=refund and refundOfId referencing the original.
• Payouts — list/get (payouts:read). Read-only; Stripe-managed.
• Time Entries — list/create/get/update/delete (time-entries:read, time-entries:write)
• Milestones — list/create/get/update/delete (milestones:read, milestones:write). Polymorphic parent: parentType: 'projects' | 'client-documents'.
• Calendar Events — list/create/get/update/delete (calendar-events:read, calendar-events:write). Events synced from Google/Microsoft/Apple are read-only.
• Transactions — list/create/get/update/delete (transactions:read, transactions:write)
• Catalog Items — list/create/get/update/delete (catalog-items:read, catalog-items:write)
• Webhooks — list/create/get/update/delete (webhooks:read, webhooks:write). secret is write-only — never returned in any response. Each webhook gets a derived hasSecret: boolean instead.

Authentication

• API keys — create at Settings → API Keys. Send as x-api-key header or Authorization: Bearer.
• OAuth 2.0 with PKCE — for third-party apps acting on behalf of a user. Register apps at Settings → OAuth Apps. Access tokens are JWTs with an organizationId claim, valid for 1 hour; refresh tokens valid for 30 days.

Cross-cutting features

• Standard error envelope — { error: { code, message, requestId, details? } }
• Pagination — page/pageSize query params; max page size 100
• Idempotency — Idempotency-Key header on POST/PATCH; 24-hour replay window
• Rate limits — 1000 req/hour per key, with X-RateLimit-Limit/Remaining/Reset headers and Retry-After on 429
• Cross-org isolation — resources outside your org return 404 not_found (not 403), preventing existence leaks

TypeScript SDK

Initial release of @clientcasa/sdk on npm. Stripe-style namespaced methods (cc.clients.listClients(), cc.invoices.createInvoice(), etc.), runtime Zod validation, typed errors, auto-retries, pagination iterators. Published via OIDC Trusted Publishing with provenance attestation.

---

Reporting issues

For API bugs, scope confusion, or breaking-change concerns, open an issue at clientcasa/sdk-typescript. For security reports, see SECURITY.md.