attio-ts-sdk 0.0.0 → 1.1.0

package/README.md

@@ -1,5 +1,12 @@
 # Attio CRM TypeScript SDK
 
+[![npm version](https://badge.fury.io/js/attio-ts-sdk.svg)](https://www.npmjs.com/package/attio-ts-sdk)
+[![ci](https://github.com/hbmartin/attio-ts-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/hbmartin/attio-ts-sdk/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/hbmartin/attio-ts-sdk/graph/badge.svg?token=Po1nDYEr5f)](https://codecov.io/gh/hbmartin/attio-ts-sdk)
+[![NPM License](https://img.shields.io/npm/l/attio-ts-sdk?color=blue)](https://github.com/hbmartin/attio-ts-sdk/blob/main/LICENSE)
+[![Context7](https://img.shields.io/badge/[]-Context7-059669)](https://context7.com/hbmartin/attio-ts-sdk)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/hbmartin/attio-ts-sdk)
+
 A modern, type-safe TypeScript SDK for the [Attio](https://attio.com) CRM API. Built with Zod v4 and a new Attio‑aware client layer that adds retries, error normalization, caching, and higher‑level helpers on top of the generated OpenAPI client.
 
 - **Create an Attio client in one line** (`createAttioClient({ apiKey })`)
@@ -8,6 +15,8 @@ A modern, type-safe TypeScript SDK for the [Attio](https://attio.com) CRM API. B
 - **Record normalization** (handles inconsistent response shapes)
 - **Metadata caching** (attributes, select options, statuses)
 - **Pagination helpers** (`paginate` + cursor handling)
+- **Response helpers** (`assertOk`, `toResult`)
+- **Offset pagination support** (`paginateOffset`)
 
 You still have full access to the generated, spec‑accurate endpoints.
 
@@ -15,9 +24,7 @@ You still have full access to the generated, spec‑accurate endpoints.
 
 - **Full Attio API Coverage** - People, companies, lists, notes, tasks, meetings, webhooks, and more
 - **Runtime Validation** - Every request and response validated with Zod v4 schemas
-- **Tiny Bundle** - Browser build under 3.5KB gzipped
 - **Tree-Shakeable** - Import only what you need
-- **Isomorphic** - Works in Node.js, Bun, Deno, and browsers
 - **TypeScript First** - Complete type definitions generated from OpenAPI spec
 - **Attio-Aware Client** - Retries, normalized errors, caching, helpers
 - **Zero Config** - Sensible defaults, just add your API key
@@ -72,6 +79,42 @@ const { data: people } = await postV2ObjectsByObjectRecordsQuery({
 });
 ```
 
+### Recommended Pattern
+
+Prefer the Attio convenience layer, throw on errors by default, and unwrap responses with helpers.
+This keeps request code compact and consistent.
+
+```typescript
+import {
+  assertOk,
+  createAttioClient,
+  createAttioSdk,
+  getV2Objects,
+  value,
+} from 'attio-ts-sdk';
+
+const client = createAttioClient({
+  apiKey: process.env.ATTIO_API_KEY,
+  responseStyle: 'data',
+  throwOnError: true,
+});
+
+const sdk = createAttioSdk({ client });
+
+const company = await sdk.records.create({
+  object: 'companies',
+  values: {
+    name: value.string('Acme Corp'),
+    domains: value.domain('acme.com'),
+    annual_revenue: value.currency(50000, 'USD'),
+  },
+});
+
+// Use assertOk with generated endpoints when you need raw access
+const objects = assertOk(await getV2Objects({ client }));
+console.log(objects);
+```
+
 ### Attio Convenience Layer
 
 The Attio helpers wrap the generated endpoints with retries, error normalization,
@@ -100,6 +143,36 @@ const matches = await searchRecords({
 });
 ```
 
+### Schema Helpers
+
+Create a schema from cached metadata and use accessors to reduce raw string keys:
+
+```typescript
+import { createSchema } from 'attio-ts-sdk';
+
+const schema = await createSchema({
+  client,
+  target: 'objects',
+  identifier: 'companies',
+});
+
+const name = schema.getAccessorOrThrow('name').getFirstValue(company);
+```
+
+### Record Value Helpers
+
+```typescript
+import { getFirstValue, getValue, value } from 'attio-ts-sdk';
+
+const values = {
+  name: value.string('Acme'),
+  domains: value.domain('acme.com'),
+};
+
+const name = getFirstValue(company, 'name');
+const domains = getValue(company, 'domains');
+```
+
 ### Client Configuration
 
 ```typescript
@@ -135,10 +208,31 @@ try {
 }
 ```
 
+If you use the generated endpoints directly, you can normalize and unwrap responses:
+
+```typescript
+import { assertOk, toResult, getV2Objects } from 'attio-ts-sdk';
+
+const objects = assertOk(await getV2Objects({ client }));
+
+const result = toResult(await getV2Objects({ client }));
+if (result.ok) {
+  console.log(result.value);
+} else {
+  console.error(result.error);
+}
+```
+
 ### Pagination Helpers
 
 ```typescript
-import { createAttioClient, paginate, getV2Meetings } from 'attio-ts-sdk';
+import {
+  createAttioClient,
+  paginate,
+  paginateOffset,
+  getV2Meetings,
+  postV2ObjectsByObjectRecordsQuery,
+} from 'attio-ts-sdk';
 
 const client = createAttioClient({ apiKey: process.env.ATTIO_API_KEY });
 
@@ -150,8 +244,123 @@ const meetings = await paginate(async (cursor) => {
   });
   return result;
 });
+
+const offsetResults = await paginateOffset(async (offset, limit) => {
+  const result = await postV2ObjectsByObjectRecordsQuery({
+    client,
+    path: { object: 'companies' },
+    body: { offset, limit },
+  });
+  return result;
+});
+```
+
+### Caching
+
+The SDK includes two levels of caching to reduce API calls and improve performance:
+
+#### Metadata Caching
+
+Attribute metadata (attributes, select options, and statuses) is automatically cached with a 5-minute TTL. This reduces redundant API calls when working with the same objects repeatedly.
+
+```typescript
+import { getAttributeOptions, getAttributeStatuses, listAttributes } from 'attio-ts-sdk';
+
+// These calls are cached for 5 minutes
+const options = await getAttributeOptions({
+  client,
+  target: 'objects',
+  identifier: 'companies',
+  attribute: 'stage',
+});
+
+// Subsequent calls with the same parameters return cached data
+const optionsAgain = await getAttributeOptions({
+  client,
+  target: 'objects',
+  identifier: 'companies',
+  attribute: 'stage',
+}); // Returns cached result, no API call
+```
+
+The metadata caches have the following defaults:
+- **Attributes cache**: 200 entries max
+- **Options cache**: 500 entries max
+- **Statuses cache**: 500 entries max
+
+When a cache reaches its limit, the oldest entry is evicted.
+
+You can customize TTL, max entries, and adapters per client:
+
+```typescript
+const client = createAttioClient({
+  apiKey: process.env.ATTIO_API_KEY,
+  cache: {
+    enabled: true,
+    metadata: {
+      ttlMs: 2 * 60 * 1000,
+      maxEntries: { attributes: 300, options: 800, statuses: 800 },
+      adapter: {
+        create: ({ scope, ttlMs, maxEntries }) =>
+          new YourCacheAdapter({ scope, ttlMs, maxEntries }),
+      },
+    },
+  },
+});
+
+// Clear metadata caches for this client
+client.cache.clear();
+```
+
+#### Client Instance Caching
+
+You can cache `AttioClient` instances to reuse them across your application. This is useful when you want to avoid creating new client instances for repeated operations.
+
+```typescript
+import { getAttioClient } from 'attio-ts-sdk';
+
+// With cache.key set, the client instance is cached and reused
+const client = getAttioClient({
+  apiKey: process.env.ATTIO_API_KEY,
+  cache: { key: 'my-app' },
+});
+
+// Returns the same cached client instance
+const sameClient = getAttioClient({
+  apiKey: process.env.ATTIO_API_KEY,
+  cache: { key: 'my-app' },
+});
+
+// Disable caching if needed
+const freshClient = getAttioClient({
+  apiKey: process.env.ATTIO_API_KEY,
+  cache: { enabled: false },
+});
 ```
 
+### Debug Hooks
+
+You can tap into request/response/error lifecycles for logging and tracing.
+
+```typescript
+const client = createAttioClient({
+  apiKey: process.env.ATTIO_API_KEY,
+  hooks: {
+    onRequest: ({ request }) => console.log("request", request.method, request.url),
+    onResponse: ({ response }) => console.log("response", response.status),
+    onError: ({ error }) => console.error("error", error.message),
+  },
+});
+
+// Or wire a logger (debug/info/warn/error)
+const clientWithLogger = createAttioClient({
+  apiKey: process.env.ATTIO_API_KEY,
+  logger: console,
+});
+```
+
+Note: `createAttioClient` always creates a new client instance. Use `getAttioClient` when you want caching behavior.
+
 ### Metadata Helpers
 
 ```typescript
@@ -329,23 +538,6 @@ const { data: webhook } = await postV2Webhooks({
 const { data: webhooks } = await getV2Webhooks({ client });
 ```
 
-### Browser Usage
-
-For browsers, import from the `/browser` entry point:
-
-```typescript
-import { createClient, getV2Self } from 'attio-ts-sdk/browser';
-
-const client = createClient({
-  baseUrl: 'https://api.attio.com',
-  headers: {
-    Authorization: `Bearer ${apiKey}`,
-  },
-});
-
-const { data: self } = await getV2Self({ client });
-```
-
 ### Error Handling
 
 ```typescript
@@ -380,10 +572,10 @@ try {
 
 ### Tools
 
+- **[Hey API](https://heyapi.dev/)**: OpenAPI client and Zod schema generation
 - **Biome**: lint and format with a single tool
 - **Vitest**: fast tests with coverage and thresholds
-- **Size Limit**: keep bundles tiny, with CI checks
-- **tsdown**: ESM builds for Node and a separate browser bundle
+- **tsdown**: ESM builds for Node
 - **CI**: lint, typecheck, test, coverage, and size comments/badges
 - **Deno-friendly**: `.ts` source imports for direct consumption
 - **OIDC + Provenance**: publish to npm and JSR via manual CI release