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.

Nothing yet.

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

The public v1 API ships with 15 resources and 75 operations.

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).
• Proposals — list/create/get/update/delete (proposals:read, proposals:write). Tiptap rich-text content is dashboard-managed only.
• 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' | 'proposals'.
• Calendar Events — list/create/get/update/delete (calendar-events:read, calendar-events:write). Events synced from Google/Microsoft/Apple are read-only.
• Inquiries — list/create/get/update/delete (inquiries:read, inquiries:write). Inquiries land in status: 'new'. The converted terminal state is set only via the dashboard conversion flow.
• 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.