@teepin/sdk 0.2.0 → 0.3.0-rc.1

package/README.md

@@ -1,501 +1,286 @@
-# TEEPIN TypeScript SDK
+# Teepin SDK for TypeScript and JavaScript
 
-Official TypeScript/JavaScript client library for the TEEPIN API.
+Teepin Web Services runs AI models in confidential enclaves (Teepin Inference) and stores your files (Teepin
+Storage). This is the official client for Node 20+ and browsers, with no dependencies.
 
-## Installation
+Links: [Docs](https://www.teepin.com/docs) · [console.teepin.com](https://console.teepin.com) · [teepin.com](https://teepin.com)
+
+## Install
 
 ```bash
 npm install @teepin/sdk
 ```
 
-Or with Yarn:
+## Authentication
 
-```bash
-yarn add @teepin/sdk
-```
+Create an API key in [console.teepin.com](https://console.teepin.com): open a project, then Settings, then API keys.
+A key belongs to one project and has the permissions you give it (for example `inference:invoke`,
+`storage:read`, `storage:write`).
 
-## Quick Start
+The client reads the key from `TEEPIN_API_KEY`, and the address from `TEEPIN_BASE_URL`, when you don't pass them.
+A value you pass always wins. The address defaults to `https://api.teepin.com`.
 
-### TypeScript
+```bash
+export TEEPIN_API_KEY=tpk_...
+```
 
 ```typescript
 import { TeepinClient } from '@teepin/sdk';
 
-const client = new TeepinClient({
-  baseUrl: 'http://localhost:8080',
-  apiKey: 'your-api-key', // Optional
-});
-
-// Deploy an instance
-const instance = await client.instances.create({
-  name: 'pytorch-training',
-  image: 'pytorch/pytorch:latest',
-  gpuVram: '25GB',
-  cpuUnits: 4,
-  memory: '16GB',
-  env: {
-    EPOCHS: '100',
-    BATCH_SIZE: '32',
-  },
-});
-
-console.log(`Instance created: ${instance.id}`);
-console.log(`Status: ${instance.status}`);
+const teepin = new TeepinClient(); // reads TEEPIN_API_KEY and TEEPIN_BASE_URL
+// or: new TeepinClient({ apiKey: 'tpk_...' })
 ```
 
-### JavaScript (CommonJS)
-
-```javascript
-const { TeepinClient } = require('@teepin/sdk');
-
-const client = new TeepinClient({
-  baseUrl: 'http://localhost:8080',
-});
+Keep your API key on your server.
 
-async function deploy() {
-  const instance = await client.instances.create({
-    name: 'my-instance',
-    image: 'nginx:latest',
-    gpuVram: '25GB',
-  });
+## Teepin Inference
 
-  console.log('Instance created:', instance.id);
-}
-
-deploy();
-```
+An OpenAI-compatible chat API. The key needs `inference:invoke`, and may be limited to some models.
 
-## Features
-
-- ✅ **Type-safe** - Full TypeScript support with complete type definitions
-- ✅ **Promise-based** - Modern async/await API
-- ✅ **Error handling** - Rich error types with type guards
-- ✅ **Well-documented** - Comprehensive JSDoc comments
-- ✅ **Tree-shakeable** - ES modules support
-- ✅ **No dependencies** - uses fetch and WebCrypto; Node 20+ and browsers
-
-## Usage Examples
-
-### List Instances
-
-```typescript
-const instances = await client.instances.list();
-
-for (const instance of instances) {
-  console.log(`${instance.id}: ${instance.name} (${instance.status})`);
-}
-```
-
-### Get Instance Details
+### Models
 
 ```typescript
-import { isNotFoundError } from '@teepin/sdk';
-
-try {
-  const instance = await client.instances.get('inst-a82e7f3');
-  console.log(`Instance: ${instance.name}`);
-  console.log(`Status: ${instance.status}`);
-  console.log(`GPU VRAM: ${instance.gpuVram}`);
-} catch (error) {
-  if (isNotFoundError(error)) {
-    console.log('Instance not found');
-  } else {
-    throw error;
-  }
+const models = await teepin.inference.listModels();
+for (const m of models) {
+  console.log(m.id, m.confidential, m.pricing.input_per_million_tokens, m.pricing.output_per_million_tokens);
 }
 ```
 
-### Delete Instance
-
-```typescript
-await client.instances.delete('inst-a82e7f3');
-console.log('Instance deleted');
-```
-
-### Deploy with Port Mappings
+### One answer
 
 ```typescript
-const instance = await client.instances.create({
-  name: 'web-app',
-  image: 'nginx:latest',
-  gpuVram: '10GB',
-  cpuUnits: 2,
-  memory: '8GB',
-  ports: [
-    { container: 80, public: 8080, protocol: 'tcp' },
-    { container: 443, public: 8443, protocol: 'tcp' },
-  ],
+const res = await teepin.inference.chat.completions.create({
+  model: 'teepin/glm-5.3',
+  messages: [{ role: 'user', content: 'What is TLS? One sentence.' }],
+  max_completion_tokens: 300,
+  chat_template_kwargs: { enable_thinking: false },
 });
+console.log(res.choices[0].message.content);
+console.log(res.usage?.total_tokens, res.meta.requestId);
 ```
 
-### Concurrent Deployments
-
-```typescript
-// Deploy 10 instances concurrently
-const deployments = Array.from({ length: 10 }, (_, i) =>
-  client.instances.create({
-    name: `worker-${i}`,
-    image: 'pytorch/pytorch:latest',
-    gpuVram: '10GB',
-  })
-);
-
-const instances = await Promise.all(deployments);
-console.log(`Deployed ${instances.length} instances`);
-```
-
-### With Labels
+### Streaming
 
 ```typescript
-const instance = await client.instances.create({
-  name: 'training-job',
-  image: 'pytorch/pytorch:latest',
-  gpuVram: '40GB',
-  labels: {
-    team: 'ml-research',
-    project: 'image-classification',
-    environment: 'production',
-  },
+const stream = await teepin.inference.chat.completions.create({
+  model: 'teepin/glm-5.3',
+  messages: [{ role: 'user', content: 'Write a haiku about the sea.' }],
+  stream: true,
+  stream_options: { include_usage: true },
 });
+for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta.content ?? '');
+console.log('\n', stream.usage?.total_tokens);
 ```
 
-### Teepin Storage
+Leaving the loop early closes the connection. A stream throws `StreamError` when the server reports a failure part
+way through, and `StreamEndedError` when it closes before the end.
 
-Works in Node 20+ and browsers (it uses `fetch` and WebCrypto, with no
-dependencies). Files on disk are in `@teepin/sdk/node`.
+### Reasoning models
 
-```typescript
-import { TeepinClient } from '@teepin/sdk';
-import { uploadFile, downloadFile } from '@teepin/sdk/node';
+Reasoning models (GLM-5.3, for example) think before they answer, and the thinking counts toward
+`max_completion_tokens`. With a small limit the answer can come back empty (`content: null`,
+`finish_reason: 'length'`). For a short answer, turn thinking off with
+`chat_template_kwargs: { enable_thinking: false }`, or give it room. The thinking itself, when the model shows it,
+is in `message.reasoning_content`.
 
-const teepin = new TeepinClient(); // reads TEEPIN_API_KEY (and TEEPIN_BASE_URL)
-await teepin.storage.createBucket('my-bucket');
+### Confidential models and attestation
 
-// Any size: one request up to 16 MiB, parallel parts above that. Each part is
-// retried on its own and the stored ETag is checked against the bytes sent.
-// resume continues an upload that was cut off.
-await uploadFile(teepin.storage, 'my-bucket', 'videos/a.mp4', './a.mp4', {
-  resume: true,
-  onProgress: (done, total) => console.log(`${done} of ${total}`),
-});
+Confidential models run in hardware enclaves that prove what code they run. Each answer says how far the enclave
+was verified for that call:
 
-// Strings, bytes, Blobs and Files (browsers), and streams of unknown size.
-await teepin.storage.upload('my-bucket', 'notes.txt', 'hello');
+```typescript
+console.log(res.meta.attestation); // 'verified', 'verified-older-release' or 'not-verified'
+const proof = await teepin.inference.getAttestation('teepin/glm-5.3'); // the live proof, to verify yourself
+```
 
-// Parallel ranges into a temporary file, renamed into place, checked against the SHA-256.
-await downloadFile(teepin.storage, 'my-bucket', 'videos/a.mp4', './copy.mp4');
-const { data } = await teepin.storage.download('my-bucket', 'notes.txt'); // into memory
+Anything less than `verified` is a warning to show, never an error. In the model list, a confidential model that
+isn't fully verified right now carries `attestation: { level, warning }`.
 
-// Every object under a prefix, or one page like folders.
-for await (const obj of teepin.storage.objects('my-bucket', 'videos/')) console.log(obj.key, obj.size);
-const page = await teepin.storage.listObjects('my-bucket', { prefix: 'videos/', delimiter: '/' });
-
-// Write only if nothing is there; read only if it changed.
-await teepin.storage.putObject('my-bucket', 'lock', '1', { ifNoneMatch: true });
-const changed = await teepin.storage.getObject('my-bucket', 'notes.txt', { ifNoneMatch: etag }); // null if not
+### Errors, retries and rate limits
 
-// Rename is instant at any size; copy writes the bytes again.
-await teepin.storage.renameObject('my-bucket', 'videos/a.mp4', 'archive/a.mp4');
-await teepin.storage.copyObject('backup', 'a.mp4', 'my-bucket', 'archive/a.mp4');
-await teepin.storage.deleteObjects('my-bucket', keys); // 1000 to a request
+Limits are per API key: by default 60 chat completions a minute and 10 at a time. A 429 is a `RateLimitError` with
+`retryAfter` in seconds.
 
-// Links that work without your key.
-const link = await teepin.storage.presignDownload('my-bucket', 'archive/a.mp4', { expiresIn: 3600 });
-const up = await teepin.storage.presignUpload('inbox', 'upload.bin', { maxBytes: 100 * 2 ** 20 });
-```
+The server bills an answer once the model has written it, even if the caller has gone. So a chat call is retried
+only when it certainly wasn't billed: on a 429, on Teepin's own `internal_error`, `upstream_error`,
+`model_unavailable` or `billing_unavailable`, and on a connection that never reached the server. It is never
+retried after a timeout or a dropped connection. Retries happen up to `maxRetries` times (default 2), waiting as
+`Retry-After` says or with backoff. A stream is never retried once it has started.
 
-**Keep your API key on your server.** Every call but a signed link sends it.
-To let a browser download or upload one object, sign a link on your server
-and hand the page only the link; signed links work from any website:
+A chat completion that isn't streamed may take up to 600 seconds. Change it per call with `{ timeout }`, or for
+the client with `teepin.inference.chatTimeout`.
 
 ```typescript
-// In the page: one PUT to the link your server signed.
-await fetch(up.url, { method: up.method, headers: up.headers, body: file });
-```
+import { isInsufficientCreditError, isRateLimitError, isNotFoundError } from '@teepin/sdk';
 
-The calls map one to one onto the API reference at
-`https://api.teepin.com/v1/openapi.json`.
+try {
+  await teepin.inference.chat.completions.create({ model: 'teepin/glm-5.3', messages: [{ role: 'user', content: 'Hi' }] });
+} catch (err) {
+  if (isInsufficientCreditError(err)) console.error('add credit in the console');
+  else if (isRateLimitError(err)) console.error(`try again in ${err.retryAfter ?? 'a few'} seconds`);
+  else if (isNotFoundError(err)) console.error('no such model, or this key may not call it');
+  else throw err;
+}
+```
 
-### Teepin Inference
+### With the OpenAI SDK
 
-OpenAI-compatible chat completions on Teepin's models, confidential ones
-included. The key needs the `inference:invoke` permission. Requests, responses
-and chunks use the API's own field names (`max_completion_tokens`,
-`finish_reason`, ...); fields the SDK does not know yet pass through and stay
-readable.
+The API is OpenAI-compatible, so OpenAI's own SDK works too:
 
 ```typescript
-import { TeepinClient } from '@teepin/sdk';
-
-const teepin = new TeepinClient(); // reads TEEPIN_API_KEY (and TEEPIN_BASE_URL)
+import OpenAI from 'openai';
 
-// The models this key may call. A confidential model that is not fully
-// verified right now carries attestation: { level, warning }.
-const models = await teepin.inference.listModels();
-for (const m of models) console.log(m.id, m.confidential, m.attestation?.warning ?? '');
-
-// A whole completion, with the response's metadata.
-const res = await teepin.inference.chat.completions.create({
-  model: 'teepin/llama-3.3-70b',
+const openai = new OpenAI({ baseURL: 'https://api.teepin.com/v1', apiKey: process.env.TEEPIN_API_KEY });
+const res = await openai.chat.completions.create({
+  model: 'teepin/glm-5.3',
   messages: [{ role: 'user', content: 'Hello' }],
-  max_completion_tokens: 256,
 });
-console.log(res.choices[0].message.content, res.usage?.total_tokens);
-console.log(res.meta.attestation, res.meta.requestId, res.meta.rateLimit); // 'verified' | 'verified-older-release' | 'not-verified' | undefined
-
-// A stream: it resolves once the headers are in (stream.meta is ready then).
-// Ask for include_usage to get the usage on the last chunk.
-const stream = await teepin.inference.chat.completions.create(
-  {
-    model: 'teepin/llama-3.3-70b',
-    messages: [{ role: 'user', content: 'Write a haiku' }],
-    stream: true,
-    stream_options: { include_usage: true },
-  },
-  { signal: AbortSignal.timeout(120_000) },
-);
-for await (const chunk of stream) process.stdout.write(chunk.choices[0]?.delta.content ?? '');
-console.log(stream.usage);
-
-// The live attestation proof of a confidential model, as the provider sends it.
-const proof = await teepin.inference.getAttestation('teepin/confidential');
 ```
 
-A stream throws `StreamError` (an `APIError`, code `stream_error`) when the
-server reports a failure part way through, and `StreamEndedError` when it
-closes without `[DONE]`. Leaving the `for await` loop early, or aborting the
-signal, closes the connection. Not verified attestation is a warning in
-`meta.attestation`, never an error.
-
-The server bills a completion once it has the model's answer, even if the
-caller has gone, so a chat call (streamed or not) is retried only when it
-certainly was not billed: on 429, on Teepin's own 500 `internal_error`, 502
-`upstream_error` and 503 `model_unavailable` or `billing_unavailable` (answers
-with the API's error envelope), and on a connection that never reached the
-server (refused, or DNS failed). It is never retried after a timeout, a
-connection reset or cut after sending, a 504, a 5xx without Teepin's envelope
-(such as a proxy's HTML 502), or a 400, 401, 402, 403, 404 or 413.
-`listModels` and `getAttestation` are retried on 429, any 5xx and any
-connection error. A stream is never retried once its headers are in.
-
-Retries happen up to `maxRetries` times (default 2; set it on the client or per
-call with `{ maxRetries }`), waiting as `Retry-After` says (at most 30 s) or
-with jittered backoff from 0.5 s to 8 s.
-
-A chat completion that is not streamed may take up to 600 s by default (a long
-answer takes minutes), not the client's `timeout`; change it per call with
-`{ timeout }` or for the client with `teepin.inference.chatTimeout`. A stream's
-timeout covers only the wait for its headers. Other calls follow the client's
-`timeout`.
-
-## Error Handling
-
-Errors from the API are `APIError` subclasses with the API's stable `code`:
+This SDK adds the attestation results, billing-safe retries and Teepin's typed errors.
 
-```typescript
-import { NotFoundError, PaymentRequiredError, ChecksumMismatchError, UploadError, isRetryable } from '@teepin/sdk';
+## Teepin Storage
 
-try {
-  await teepin.storage.statObject('my-bucket', 'nope');
-} catch (err) {
-  if (err instanceof NotFoundError) {
-    // 404: err.code is bucket_not_found or object_not_found
-  } else if (err instanceof PaymentRequiredError && err.onHold) {
-    // no credit; held data is deleted after err.deleteAfter
-  } else if (isRetryable(err)) {
-    // the network or a busy server, after the client's own retries
-  } else {
-    throw err;
-  }
-}
-```
+Buckets and files. Files are encrypted on this device and sent straight to the storage network, and every byte read
+is verified on this device before it is used: no file byte passes through Teepin's API. The key needs `storage:read`
+to read and `storage:write` to write.
 
-Also: `UnauthorizedError` (401), `ForbiddenError` (403, e.g. no storage:write),
-`ConflictError` (409), `PreconditionFailedError` (412), `TooLargeError` (413),
-`RateLimitError` (429), `ConnectionError`, `ObjectChangedError`,
-`ChecksumMismatchError`, `UploadError` (with `uploadId`, for resuming), and for
-inference streams `StreamError` and `StreamEndedError`. Every API error carries
-`status`, `code`, `type` (inference), `serverMessage`, `requestId` for support
-and `retryAfter` (seconds, when the server sent Retry-After). Helpers:
-`isNotFoundError`, `isRateLimitError`, `isInsufficientCreditError` (402),
-`isPermissionError` (403) and `isRetryable`. Requests that fail for a passing
-reason are retried with backoff, `maxRetries` times (default 4; 2 for
-inference).
-
-## Configuration
+### Buckets
 
-### Environment Variables
-
-`new TeepinClient()` reads these when `apiKey` or `baseUrl` isn't given, as OpenAI's SDKs read `OPENAI_API_KEY`
-and `OPENAI_BASE_URL`. A value given in code always wins.
-
-```bash
-export TEEPIN_API_KEY=your-api-key
-export TEEPIN_BASE_URL=https://api.teepin.com # optional; the default
+```typescript
+await teepin.storage.createBucket('my-bucket');
+const buckets = await teepin.storage.listBuckets();
+await teepin.storage.deleteBucket('my-bucket'); // only when it is empty
 ```
 
-### Custom Client Configuration
+### Put and get
 
 ```typescript
-const client = new TeepinClient({
-  baseUrl: 'https://api.teepin.com', // the default
-  apiKey: process.env.TEEPIN_API_KEY,
-  timeout: 60000, // 60 seconds
-});
+// Strings, bytes, Blobs, Files and streams.
+await teepin.storage.upload('my-bucket', 'notes.txt', 'hello');
+
+const { object, data } = await teepin.storage.download('my-bucket', 'notes.txt');
+console.log(object.size, new TextDecoder().decode(data));
+
+const info = await teepin.storage.statObject('my-bucket', 'notes.txt'); // size, etag, contentType
 ```
 
-## API Reference
+### Large files
 
-### TeepinClient
+Files on disk use `@teepin/sdk/node`. Files up to 16 MiB are packed together, and larger ones go in parallel
+parts, each retried on its own. A large file's upload is journaled on disk, so `resumeUploads` finishes it after a
+crash or a lost connection; `uploadFiles` uploads many files as one such run. A download fetches ranges in parallel
+and checks the SHA-256.
 
 ```typescript
-class TeepinClient {
-  constructor(config?: TeepinConfig);
+import { uploadFile, downloadFile, resumeUploads } from '@teepin/sdk/node';
 
-  readonly instances: InstancesService;
-  readonly storage: StorageService;
-  readonly inference: InferenceService;
-}
+await uploadFile(teepin.storage, 'my-bucket', 'videos/a.mp4', './a.mp4', {
+  onProgress: (done, total) => console.log(`${done} of ${total}`),
+});
+await downloadFile(teepin.storage, 'my-bucket', 'videos/a.mp4', './copy.mp4');
+
+await resumeUploads(teepin.storage); // finishes what an earlier process left unfinished
 ```
 
-### InferenceService
+On a slow connection, uploads use smaller requests. The client measures how fast its uploads to storage go (a request
+that gets no answer in time counts too, so a slow connection is noticed from the first requests), and when a request
+would take more than about 4 minutes, packs shrink below 9 MiB, an object too large for one such request (over 5 MiB)
+goes in parts instead of a pack, and new uploads use smaller parts (down to 5 MiB, the smallest allowed). A file that
+still can't be sent, because even 5 MiB parts would be too slow or it would need more than 3,000 parts, throws
+`TooLargeError` with `reason` `"connection_speed"` before anything is sent.
+
+### List
 
 ```typescript
-interface InferenceService {
-  listModels(options?: InferenceRequestOptions): Promise<Model[]>;
-  getAttestation(modelId: string, options?: InferenceRequestOptions): Promise<Record<string, unknown>>;
-  chat: {
-    completions: {
-      create(body: ChatCompletionCreateParams & { stream: true }, options?): Promise<ChatCompletionStream>;
-      create(body: ChatCompletionCreateParams, options?): Promise<ChatCompletion & { meta: ResponseMeta }>;
-    };
-  };
-}
+// Every object under a prefix.
+for await (const obj of teepin.storage.objects('my-bucket', 'videos/')) console.log(obj.key, obj.size);
 
-interface InferenceRequestOptions {
-  signal?: AbortSignal;
-  maxRetries?: number;
-  timeout?: number;
-  headers?: Record<string, string>;
-}
+// One page, with "folders".
+const page = await teepin.storage.listObjects('my-bucket', { prefix: 'videos/', delimiter: '/' });
 ```
 
-### InstancesService
+### Rename, copy and delete
 
 ```typescript
-interface InstancesService {
-  /**
-   * Create a new instance
-   */
-  create(request: CreateInstanceRequest): Promise<Instance>;
-
-  /**
-   * List all instances
-   */
-  list(): Promise<Instance[]>;
-
-  /**
-   * Get instance by ID
-   */
-  get(instanceId: string): Promise<Instance>;
-
-  /**
-   * Delete an instance
-   */
-  delete(instanceId: string): Promise<void>;
-
-  /**
-   * List available instance types
-   */
-  listTypes(): Promise<InstanceType[]>;
-
-  /**
-   * Get instance metrics
-   */
-  metrics(instanceId: string): Promise<Record<string, any>>;
-}
+await teepin.storage.renameObject('my-bucket', 'videos/a.mp4', 'archive/a.mp4'); // instant at any size
+await teepin.storage.copyObject('backup', 'a.mp4', 'my-bucket', 'archive/a.mp4'); // read and uploaded again, to backup/a.mp4
+await teepin.storage.deleteObject('my-bucket', 'notes.txt');
+await teepin.storage.deleteObject('my-bucket', 'notes.txt', { ifMatch: etag }); // only if it still has statObject's etag, else PreconditionFailedError
+await teepin.storage.deleteObjects('my-bucket', ['a.txt', 'b.txt']); // up to 1000 a request
 ```
 
-### Types
+### Share links
 
-```typescript
-interface CreateInstanceRequest {
-  name: string;
-  image: string;
-  gpuVram?: string;
-  cpuUnits?: number;
-  memory?: string;
-  env?: Record<string, string>;
-  ports?: PortMapping[];
-  labels?: Record<string, string>;
-}
+A share link is a page on the console that anyone holding it can open with no sign-in, to preview or save one
+object, for up to 24 hours (15 minutes by default). It needs `storage:read`. Its token is sealed, so the link names
+no bucket or key, and rides in the URL's fragment (`https://console.teepin.com/l#…`). `openLink` opens one in code,
+with no API key: the bytes come straight from the storage network and are verified on this device. A download that
+began while the link was valid may finish after it expires, for up to 24 hours more.
 
-interface Instance {
-  id: string;
-  name: string;
-  image: string;
-  status: string;
-  gpuVram?: string;
-  allocatedVram?: string;
-  cpuUnits: number;
-  memory: string;
-  endpoint?: string;
-  internalIp?: string;
-  createdAt: Date;
-  updatedAt: Date;
-  labels?: Record<string, string>;
-}
-```
-
-## Development
+```typescript
+import { openLink } from '@teepin/sdk';
 
-### Build
+const link = await teepin.storage.createLink('my-bucket', 'reports/q3.pdf', { expiresIn: 3600 });
+console.log(link.url, link.expiresAt);
 
-```bash
-npm run build
+const shared = await openLink(link.url); // InvalidLinkError once it has expired
+console.log(shared.name, shared.size, shared.contentType);
+const body = shared.stream(); // or shared.read(offset, length), or shared.downloadTo(sink)
+shared.close();
 ```
 
-### Watch Mode
+## Errors
 
-```bash
-npm run dev
-```
+Errors from the API are `APIError` subclasses with the API's stable `code`, `status`, `serverMessage` and
+`requestId` (for support):
 
-### Lint
+- `UnauthorizedError` (401), `PaymentRequiredError` (402), `ForbiddenError` (403), `NotFoundError` (404),
+  `ConflictError` (409), `PreconditionFailedError` (412), `TooLargeError` (413; `reason` is `"connection_speed"`
+  when the connection measured too slow to send a file), `RateLimitError` (429);
+- `ConnectionError` when the server couldn't be reached;
+- `StreamError` and `StreamEndedError` for inference streams;
+- `DataIntegrityError` (with `ChecksumMismatchError` under it), `ObjectChangedError`, `KeyErasedError`,
+  `StorageUnavailableError` and `FileChangedError` for storage, and `InvalidLinkError` (a `ForbiddenError`) for a
+  share link that is damaged or has expired.
 
-```bash
-npm run lint
-```
+Helpers: `isNotFoundError`, `isRateLimitError`, `isInsufficientCreditError`, `isPermissionError` and
+`isRetryable`. Storage calls that fail for a passing reason are retried with backoff, up to `maxRetries` times
+(default 4).
 
-### Format
+## Configuration
 
-```bash
-npm run format
+```typescript
+const teepin = new TeepinClient({
+  apiKey: 'tpk_...', // default: TEEPIN_API_KEY
+  baseUrl: 'https://api.teepin.com', // default: TEEPIN_BASE_URL, else this
+  timeout: 60_000, // milliseconds for a call that isn't a transfer or a chat completion
+  maxRetries: 4, // 0 turns retries off
+});
 ```
 
-## Examples
+## Other APIs
 
-See the `examples/` directory for more examples:
+The SDK also has clients for services that aren't offered yet. They answer 404 until they launch.
 
-- `basic.ts` - Basic usage
-- `concurrent.ts` - Concurrent deployments
-- `storage.ts` - Create a bucket, upload/download/delete objects, mint a signed link
-- `inference.ts` - List models, chat, stream and check attestation
+## Examples
 
-Run examples:
+`examples/inference.mts` and `examples/storage.mts` run with Node 22.6 or newer:
 
 ```bash
-# Install ts-node
-npm install -g ts-node
-
-# Run example
-ts-node examples/basic.ts
+npm run build
+TEEPIN_API_KEY=tpk_... node --experimental-strip-types examples/inference.mts
 ```
 
-## Contributing
+## Development
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+```bash
+npm install
+npm run build
+npm test
+npm run typecheck
+```
 
 ## License
 
-Apache License 2.0
+Apache License 2.0. See [LICENSE](LICENSE).