attio-ts-sdk 0.0.0 → 1.0.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 })`)
@@ -15,9 +22,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
@@ -152,6 +157,69 @@ const meetings = await paginate(async (cursor) => {
 });
 ```
 
+### 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 limits:
+- **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.
+
+#### 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 },
+});
+```
+
+Note: `createAttioClient` always creates a new client instance. Use `getAttioClient` when you want caching behavior.
+
 ### Metadata Helpers
 
 ```typescript
@@ -329,23 +397,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 +431,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