@sentroy-co/client-sdk 2.6.3 → 2.8.0

package/README.md

@@ -2,11 +2,11 @@
   <img src="https://sentroy.com/business/sentroy-logo-light.png" alt="Sentroy" width="240" />
 </p>
 
-<h3 align="center">Sentroy Client SDK for TypeScript</h3>
+<h3 align="center">Sentroy Client SDK</h3>
 
 <p align="center">
-  TypeScript SDK to interact with the Sentroy platform API + opt-in React components.<br />
-  Manage mail (domains, mailboxes, templates, inbox, send) and storage (buckets, media) from a single entry point.
+  Official TypeScript SDK for the <a href="https://sentroy.com">Sentroy</a> business mail &amp; storage platform.<br />
+  Send transactional and bulk email, manage domains and mailboxes, run an inbox, store and serve media — from one typed client.
 </p>
 
 <p align="center">
@@ -15,667 +15,115 @@
   <a href="https://github.com/Sentroy-Co/client-sdk/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/@sentroy-co/client-sdk.svg" alt="license" /></a>
 </p>
 
+<p align="center">
+  <a href="https://docs.sentroy.com"><strong>Documentation</strong></a>
+  &nbsp;·&nbsp;
+  <a href="https://docs.sentroy.com/mail">Mail</a>
+  &nbsp;·&nbsp;
+  <a href="https://docs.sentroy.com/storage">Storage</a>
+  &nbsp;·&nbsp;
+  <a href="https://docs.sentroy.com/react">React components</a>
+  &nbsp;·&nbsp;
+  <a href="https://status.sentroy.com">Status</a>
+</p>
+
 ---
 
-## Installation
+## What's in the box
+
+- **Mail** — verified domains, mailboxes, multi-language templates, IMAP-backed inbox, transactional and bulk send, suppressions, webhooks, audience lists, deliverability logs.
+- **Storage** — isolated buckets, multipart uploads, image and media transformations, signed download URLs.
+- **Env Vault** — runtime env variable management (`@sentroy-co/client-sdk/vault`) — change a value in the dashboard, your app picks it up on the next read; no rebuild.
+- **React drop-ins** — `<MediaManager />`, `<MediaManagerTrigger />` and `<EnvProvider>` / `useEnv()` (`@sentroy-co/client-sdk/react` + `@sentroy-co/client-sdk/vault/react`).
+- **One client, two backends** — point at `https://sentroy.com` for the hosted platform, or your own deployment for self-hosted. Same API, same types.
+
+## Install
 
 ```bash
 npm install @sentroy-co/client-sdk
 ```
 
-## Quick Start
+## First request
 
 ```ts
 import { Sentroy } from "@sentroy-co/client-sdk"
 
 const sentroy = new Sentroy({
-  baseUrl: "https://sentroy.com",
+  baseUrl: "https://sentroy.com",   // or your self-hosted URL
   companySlug: "my-company",
-  accessToken: "stk_...",
-})
-```
-
-> Access tokens can be created from **Admin > Access Tokens** in the Sentroy dashboard.
-
-## Usage
-
-### Domains
-
-```ts
-// List all domains
-const domains = await sentroy.domains.list()
-
-// Get a single domain
-const domain = await sentroy.domains.get("domain-id")
-```
-
-### Mailboxes
-
-```ts
-// List all mailbox accounts
-const mailboxes = await sentroy.mailboxes.list()
-```
-
-### Templates
-
-```ts
-// List all templates
-const templates = await sentroy.templates.list()
-
-// Get a template by ID
-const template = await sentroy.templates.get("template-id")
-```
-
-Templates support multiple languages via `LocalizedString`. A field can be a plain string or an object keyed by language code:
-
-```jsonc
-// Example template response
-{
-  "id": "b3f1a2c4-...",
-  "name": { "en": "Welcome Email", "tr": "Hosgeldin E-postasi" },
-  "subject": { "en": "Welcome, {{name}}!", "tr": "Hosgeldin, {{name}}!" },
-  "mjmlBody": { "en": "<mjml>...</mjml>", "tr": "<mjml>...</mjml>" },
-  "variables": ["name", "company"],
-  "domainId": "a1b2c3d4-...",
-  "domainName": "example.com",
-  "createdAt": "2026-01-15T10:30:00.000Z",
-  "updatedAt": "2026-04-10T14:22:00.000Z"
-}
-```
-
-Use the `variables` array to know which placeholders (`{{name}}`, `{{company}}`) the template expects.
-
-### Inbox
-
-```ts
-// List messages
-const messages = await sentroy.inbox.list({
-  mailbox: "info@example.com",
-  folder: "INBOX",
-  page: 1,
-  limit: 20,
-})
-
-// Get a single message
-const message = await sentroy.inbox.get(1234, {
-  mailbox: "info@example.com",
-})
-
-// List IMAP folders
-const folders = await sentroy.inbox.listFolders("info@example.com")
-
-// Get a thread by subject
-const thread = await sentroy.inbox.getThread("Re: Project update", "info@example.com")
-
-// Mark as read / unread
-await sentroy.inbox.markAsRead(1234, { mailbox: "info@example.com" })
-await sentroy.inbox.markAsUnread(1234, { mailbox: "info@example.com" })
-
-// Move message
-await sentroy.inbox.move(1234, "Trash", {
-  from: "INBOX",
-  mailbox: "info@example.com",
-})
-
-// Delete message
-await sentroy.inbox.delete(1234, { mailbox: "info@example.com" })
-```
-
-### Audience
-
-Manage contacts and audience lists from the SDK. Useful for building
-your own newsletter signup form, syncing customers from another system,
-or assembling segments for a campaign.
-
-```ts
-// List + paginate contacts (filter by status / tags)
-const { contacts, total, page, limit } = await sentroy.audience.contacts.list({
-  page: 1,
-  limit: 50,
-  status: "active",
-  tags: ["customer", "vip"],
-})
-
-// Email-prefix autocomplete (capped at 10 server-side)
-const matches = await sentroy.audience.contacts.search("alex@")
-
-// Create a contact
-const contact = await sentroy.audience.contacts.create({
-  email: "user@example.com",
-  name: "Jane Doe",
-  tags: ["beta-tester"],
-  metadata: { signupSource: "landing-2026-q2" },
-})
-
-// Patch — pass any subset of fields. Use `status` to mark unsubscribed.
-await sentroy.audience.contacts.update(contact.id, { tags: ["customer"] })
-
-// Soft-delete (sets status: "unsubscribed" — record is preserved)
-await sentroy.audience.contacts.delete(contact.id)
-```
-
-Audience lists are simple groupings; a single contact can belong to many.
-
-```ts
-// CRUD audience lists
-const lists = await sentroy.audience.lists.list()
-const list = await sentroy.audience.lists.create({
-  name: "Newsletter — May 2026",
-  description: "Opt-ins from the homepage form",
-})
-await sentroy.audience.lists.delete(list.id)
-
-// Membership — scoped to a single list id
-const members = sentroy.audience.lists.members(list.id)
-await members.add(contact.id)
-const inList = await members.list()
-await members.remove(contact.id)
-```
-
-### Suppressions
-
-Suppressed addresses are skipped at send time. Bounces and complaints
-are added automatically; the API is for manually honoring off-platform
-opt-outs or removing a stale entry.
-
-```ts
-const suppressions = await sentroy.suppressions.list({
-  domainId: "domain-id",
-  reason: "complaint",
-  page: 1,
-  limit: 50,
-})
-
-const added = await sentroy.suppressions.add({
-  email: "leaving@example.com",
-  domainId: "domain-id",
-  reason: "manual",
-})
-
-await sentroy.suppressions.remove(added.id)
-```
-
-### Webhooks
-
-Subscribe to delivery events on a per-domain basis. The `secret`
-returned at create time signs every delivery — store it and verify the
-HMAC on your endpoint.
-
-```ts
-const webhook = await sentroy.webhooks.create({
-  url: "https://example.com/webhooks/sentroy",
-  events: ["sent", "bounced", "opened", "clicked", "unsubscribed"],
-  domainId: "domain-id",
-})
-console.log(webhook.secret) // Returned ONCE — store it now
-
-const all = await sentroy.webhooks.list()           // every webhook
-const scoped = await sentroy.webhooks.list("domain-id")
-
-await sentroy.webhooks.update(webhook.id, { active: false })
-await sentroy.webhooks.delete(webhook.id)
-```
-
-### Logs
-
-Query the mail log to debug delivery issues, surface per-message status
-in your own UI, or build a customer-facing activity timeline.
-
-```ts
-const logs = await sentroy.logs.list({
-  status: "bounced",
-  domainId: "domain-id",
-  from: "2026-05-01T00:00:00Z",
-  to: "2026-05-31T23:59:59Z",
-  page: 1,
-  limit: 100,
-})
-
-const log = await sentroy.logs.get(logs[0].id)
-console.log(log.openedAt, log.clickedAt) // tracking timestamps if enabled
-```
-
-### Send Email
-
-```ts
-// Send with a template (uses default language)
-const result = await sentroy.send.email({
-  to: "user@example.com",
-  from: "info@example.com",
-  subject: "Welcome!",
-  domainId: "domain-id",
-  templateId: "template-id",
-  variables: {
-    name: "John",
-    company: "Acme",
-  },
-})
-
-// Send with a specific language
-const result = await sentroy.send.email({
-  to: "user@example.com",
-  from: "info@example.com",
-  subject: "Hosgeldin!",
-  domainId: "domain-id",
-  templateId: "template-id",
-  lang: "tr",
-  variables: { name: "Ahmet" },
+  accessToken: "stk_...",            // Dashboard → Admin → Access Tokens
 })
 
-// Send with raw HTML
-const result = await sentroy.send.email({
-  to: ["user1@example.com", "user2@example.com"],
-  from: "info@example.com",
-  subject: "Hello",
-  domainId: "domain-id",
-  html: "<h1>Hello World</h1>",
-})
-
-// Send with attachments
-const result = await sentroy.send.email({
-  to: "user@example.com",
-  from: "info@example.com",
-  subject: "Invoice",
-  domainId: "domain-id",
-  html: "<p>Please find your invoice attached.</p>",
-  attachments: [
-    {
-      filename: "invoice.pdf",
-      content: base64String,
-      contentType: "application/pdf",
-    },
-  ],
+// Send your first transactional email
+await sentroy.send.email({
+  from: "noreply@yourdomain.com",
+  to: ["customer@example.com"],
+  subject: "Welcome to Acme",
+  html: "<p>Glad you're here.</p>",
 })
 ```
 
-### Buckets
-
-Storage is organized into **buckets** — isolated containers with their own
-visibility (public vs private) and usage counters.
+## Upload a file
 
 ```ts
-// List all buckets in the company
-const buckets = await sentroy.buckets.list()
+const file = new File([blob], "invoice.pdf", { type: "application/pdf" })
 
-// Get a single bucket by its slug
-const bucket = await sentroy.buckets.get("product-assets")
-
-// Create a bucket (slug auto-derived from name if omitted)
-const created = await sentroy.buckets.create({
-  name: "User Uploads",
-  description: "Avatars and profile media",
-  isPublic: false,
+const media = await sentroy.media.upload({
+  bucketSlug: "invoices",
+  file,
 })
 
-// Update a bucket — toggling isPublic cascades to every file's ACL
-await sentroy.buckets.update("product-assets", { isPublic: true })
-
-// Delete a bucket (409 if it has files; use force to purge everything)
-await sentroy.buckets.delete("product-assets", { force: true })
+console.log(media.url) // signed URL, served from the CDN
 ```
 
-### Media
-
-Upload, list, download, and delete files inside a bucket. The same token
-that authorizes mail calls also authorizes storage calls.
-
-```ts
-// List files in a bucket
-const { items, total } = await sentroy.media.list("product-assets", {
-  type: "image",
-  limit: 50,
-})
-
-// Get a single media record
-const media = await sentroy.media.get("product-assets", mediaId)
-
-// Upload — browser (File from <input>)
-const input = document.querySelector<HTMLInputElement>("input[type=file]")!
-const file = input.files![0]
-const uploaded = await sentroy.media.upload("product-assets", {
-  body: file,
-  folder: "products",
-  tags: ["v1", "cover"],
-})
-console.log(uploaded.url) // Public URL from the CDN
-
-// Upload — Node.js (Blob from fs)
-import { openAsBlob } from "node:fs"
-const blob = await openAsBlob("./photo.jpg")
-const uploaded = await sentroy.media.upload("product-assets", {
-  body: blob,
-  filename: "photo.jpg",
-  isPublic: true,
-})
-
-// Download — streams from the storage backend; works for both public
-// and private buckets (auth-gated for private).
-const blob = await sentroy.media.download("product-assets", mediaId)
-// Variant: ask for a pre-generated thumbnail width (falls back to
-// original if that size wasn't generated for this file).
-const thumb = await sentroy.media.download("product-assets", mediaId, {
-  quality: 500,
-})
-
-// Delete — removes S3 objects (original + thumbnails) + Media record
-await sentroy.media.delete("product-assets", mediaId)
-```
+That's the smallest useful surface. Every other resource (`domains`, `mailboxes`, `templates`, `inbox`, `audience`, `webhooks`, `suppressions`, `logs`, `buckets`, `media`) follows the same `sentroy.<resource>.<verb>(...)` shape with full TypeScript types.
 
-#### Thumbnail URL helpers
+## Env Vault
 
-When you upload an image, the CDN auto-generates several thumbnail
-sizes (`media.imageMeta.thumbnails`). Showing the original 4000-px JPG
-in a 56-px avatar wastes bandwidth and slows render. Use these helpers
-to pick the right URL for the display target:
+Manage your env vars in the dashboard at [vault.sentroy.com](https://vault.sentroy.com), bootstrap your deploy with one token, and read values via a typed helper — no rebuild on change.
 
 ```ts
-import {
-  pickThumbnailUrl,
-  pickPresetThumbnailUrl,
-  THUMBNAIL_PRESETS,
-} from "@sentroy-co/client-sdk"
-
-// Manual target (px) — pass display size * 2 for retina
-const avatarUrl = pickThumbnailUrl(media, 56 * 2)
-
-// Semantic preset — avatar / card / preview / hero
-const cardUrl = pickPresetThumbnailUrl(media, "card") // → ~500px
-const previewUrl = pickPresetThumbnailUrl(media, "preview") // → ~960px
-```
-
-The helper picks the smallest thumbnail that still **covers** the
-target (so you never upscale), then falls back through:
+// server side
+import { getEnv, getEnvOrThrow, preloadEnv } from "@sentroy-co/client-sdk/vault"
 
-1. `thumbnail.url` if the backend exposed it directly,
-2. CDN-prefix + `thumbnail.fileName` derived from `media.url`,
-3. proxy `media.downloadUrl?quality=N` for private buckets,
-4. `media.url` / `media.downloadUrl` if no thumbnails exist
-   (non-image, or image upload before thumbnails were generated).
-
-Returns `undefined` only when the media has no public URL at all.
-
-| Preset      | Target px | Use case |
-|-------------|-----------|----------|
-| `avatar`    | 128       | Round chips, 28-64 px display @2x |
-| `card`      | 500       | Grid / list cards, 200-300 px |
-| `preview`   | 960       | Modal / detail view |
-| `hero`      | 1600      | Full-bleed hero, edge cases |
-
-## Error Handling
-
-```ts
-import { Sentroy, SentroyError } from "@sentroy-co/client-sdk"
-
-try {
-  await sentroy.send.email({ ... })
-} catch (err) {
-  if (err instanceof SentroyError) {
-    console.error(err.statusCode) // 401, 403, 500, etc.
-    console.error(err.message)    // Human-readable error
-  }
-}
+await preloadEnv() // optional fail-fast at boot
+const dbUrl = await getEnv("DATABASE_URL")
+const turnstile = await getEnvOrThrow("BETTER_AUTH_TURNSTILE_SECRET")
 ```
 
-## Configuration
-
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `baseUrl` | `string` | Yes | Sentroy instance URL (e.g. `https://sentroy.com`) |
-| `companySlug` | `string` | Yes | Your company slug |
-| `accessToken` | `string` | Yes | Access token (`stk_...`) |
-| `timeout` | `number` | No | Request timeout in ms (default: `30000`) |
-
-## React components (`@sentroy-co/client-sdk/react`)
-
-Optional subpath. Only loaded if you import it; React + react-dom are
-declared as **optional peer dependencies** so server-only consumers
-don't need to install them.
-
-```bash
-npm install react react-dom
-```
-
-### `MediaManager`
-
-Drop-in storage browser/uploader for end-user apps. Talks to the same
-Sentroy client you already use; renders Tailwind classes (host app's
-Tailwind setup is reused — the package ships no styles).
-
 ```tsx
-"use client"
+// React: SSR-injected provider + hook (no FOUC)
+import { getPublicEnvs } from "@sentroy-co/client-sdk/vault"
+import { EnvProvider, useEnv } from "@sentroy-co/client-sdk/vault/react"
 
-import { Sentroy } from "@sentroy-co/client-sdk"
-import { MediaManager } from "@sentroy-co/client-sdk/react"
+// app/layout.tsx (server)
+const envs = await getPublicEnvs()
+return <EnvProvider envs={envs}>{children}</EnvProvider>
 
-const client = new Sentroy({
-  baseUrl: "https://sentroy.com",
-  companySlug: "my-company",
-  accessToken: "stk_...",
-})
-
-export default function Page() {
-  return (
-    <MediaManager
-      client={client}
-      multiple
-      accept="image/*"
-      onChange={(selected) => console.log(selected)}
-      onSelect={(selected) => console.log("confirmed:", selected)}
-    />
-  )
-}
+// any "use client" component
+const siteKey = useEnv("TURNSTILE_SITE_KEY")
 ```
 
-#### Features
-
-- Bucket selector (auto-picks first if `bucketSlug` not provided)
-- Search (filename) + file-type filter (image / video / audio / pdf / doc / archive / code)
-- Upload via button **and** drag-and-drop
-- Single or multi selection (`multiple` prop)
-- `initialValue` accepts `Media[]` or `string[]` (id list) — pre-selected
-  on mount, fires `onChange` immediately so parent state stays in sync
-- Press `Space` while a card is selected → opens it in fullscreen
-  **Lightbox** (image / video / audio render natively, others get a
-  download fallback). `Esc` closes, `←/→` step through siblings
-- Detail pane on the right (large screens) — preview, metadata,
-  delete, "Use selection" CTA when `onSelect` provided
-
-#### Props
-
-| Prop                 | Type                                                  | Required | Description |
-|----------------------|-------------------------------------------------------|:-:|:--|
-| `client`             | `Sentroy`                                             | Yes | The configured client instance |
-| `bucketSlug`         | `string`                                              |  | Initial bucket; default = first one in the list |
-| `multiple`           | `boolean`                                             |  | Allow multi-selection. Default `false` |
-| `maxItems`           | `number`                                              |  | Cap for multi-mode. New selections are silently blocked once reached. Ignored when `multiple=false` |
-| `accept`             | `string`                                              |  | File type filter — applies to upload **and** the grid. Same syntax as `<input accept>`: `"image/*"`, `"image/png,image/jpeg"`, `".pdf,.docx"`, comma-separated combos |
-| `initialValue`       | `Array<Media \| string>`                              |  | Pre-selected items (objects or ids) |
-| `onChange`           | `(selected: Media[]) => void`                         |  | Fires on every selection change |
-| `onSelect`           | `(selected: Media[]) => void`                         |  | Fires on confirm — picker dialogs use this |
-| `bucketFilter`       | `(b: Bucket) => boolean`                              |  | Filter the bucket dropdown — hide system buckets |
-| `showDetailsPane`    | `boolean`                                             |  | Default `true` |
-| `showBucketSelector` | `boolean`                                             |  | Default `true` |
-| `className`          | `string`                                              |  | Root wrapper class |
-| `classNames`         | `MediaManagerClassNames`                              |  | Per-region class overrides (see theming) |
-
-#### Theming
-
-The component uses Tailwind utility classes that consume your design
-tokens (`bg-background`, `text-foreground`, `border-border`,
-`text-muted-foreground`, `bg-muted`, etc.). Drop-in usage in any
-shadcn-style codebase needs no extra setup.
-
-For finer control, override individual sections via `classNames`:
+Bootstrap is a single env: `SENTROY_ENV_API_KEY`. Public/private split is enforced server-side — the React hook only ever sees `public: true` variables. Full reference at [docs.sentroy.com/env-vault](https://docs.sentroy.com/env-vault).
 
-```tsx
-<MediaManager
-  client={client}
-  className="h-[600px] rounded-2xl border-purple-200"
-  classNames={{
-    toolbar: "bg-purple-50",
-    uploadButton: "bg-purple-600 text-white",
-    cardSelected: "ring-purple-400 border-purple-400",
-    grid: "sm:grid-cols-2 md:grid-cols-3", // override grid density
-  }}
-/>
-```
-
-Available keys: `root`, `toolbar`, `searchInput`, `filterSelect`,
-`uploadButton`, `bucketSelect`, `grid`, `card`, `cardSelected`,
-`thumbnail`, `cardMeta`, `empty`, `details`, `dropZoneOverlay`.
+## Self-hosted vs hosted
 
-When you migrate to a different theme system later, change tokens in
-one place — every Tailwind utility resolves through your `globals.css`.
+The SDK is identical in both modes. Only `baseUrl` changes:
 
-### `MediaManagerTrigger`
+| Mode | `baseUrl` |
+|---|---|
+| Sentroy Cloud (hosted) | `https://sentroy.com` |
+| Self-hosted | `https://your-sentroy-host` |
 
-A wrapper that turns **any** clickable element into a media picker — when
-the user clicks the `trigger`, a portal-rendered modal opens with
-`MediaManager` inside, and `onSelect` fires with the confirmed selection.
+Pick the deployment that fits your compliance, latency and cost requirements. Migrate either direction without changing application code.
 
-The use case: you don't want a giant manager taking up real estate on your
-profile/settings page — you just want a "Change avatar" button (or even
-a clickable avatar thumbnail) that pops the picker on demand.
+## Documentation
 
-```tsx
-"use client"
-
-import { Sentroy } from "@sentroy-co/client-sdk"
-import { MediaManagerTrigger } from "@sentroy-co/client-sdk/react"
+Full reference, interactive examples, and multi-language code samples (TypeScript, Go, Python, PHP, cURL) live at:
 
-const client = new Sentroy({
-  baseUrl: "https://sentroy.com",
-  companySlug: "my-company",
-  accessToken: "stk_...",
-})
-
-export function AvatarPicker({
-  current,
-  onChange,
-}: {
-  current: string | null
-  onChange: (url: string) => void
-}) {
-  return (
-    <MediaManagerTrigger
-      client={client}
-      maxItems={1}
-      accept="image/*"
-      title="Choose your avatar"
-      description="Pick an existing image or upload a new one."
-      trigger={
-        <button className="rounded-full ring-2 ring-border hover:ring-primary">
-          {current ? (
-            <img src={current} alt="" className="size-10 rounded-full" />
-          ) : (
-            <span className="grid size-10 place-items-center rounded-full bg-muted text-xs">
-              ?
-            </span>
-          )}
-        </button>
-      }
-      onSelect={(media) => {
-        if (media[0]?.url) onChange(media[0].url)
-      }}
-    />
-  )
-}
-```
+**[docs.sentroy.com](https://docs.sentroy.com)**
 
-#### Multi-select with cap
-
-```tsx
-<MediaManagerTrigger
-  client={client}
-  maxItems={5}
-  accept="image/*,video/*"
-  trigger={<Button>Add gallery items</Button>}
-  onSelect={(media) => setGallery(media)}
-/>
-```
-
-`maxItems > 1` automatically enables multi-mode. Once the user reaches
-the cap, additional clicks on unselected cards are silently no-op'd —
-they have to deselect something to swap.
-
-#### Controlled mode
-
-If you want the parent to drive open/close (e.g. opening from a context
-menu), pass `open` + `onOpenChange`. The `trigger` is still rendered so
-its click also opens the modal — to render only the modal, pass an empty
-fragment for `trigger`.
-
-```tsx
-const [open, setOpen] = useState(false)
-
-<MediaManagerTrigger
-  client={client}
-  open={open}
-  onOpenChange={setOpen}
-  trigger={<></>}
-  onSelect={(media) => { /* … */ }}
-/>
-```
-
-#### Props
-
-| Prop               | Type                              | Required | Description |
-|--------------------|-----------------------------------|:-:|:--|
-| `client`           | `Sentroy`                         | Yes | Same client you pass to `MediaManager` |
-| `trigger`          | `ReactNode`                       | Yes | The clickable element. Wrapped in `<span role="button">` with click + keyboard (Enter / Space) handlers |
-| `onSelect`         | `(selected: Media[]) => void`     | Yes | Fires when user confirms; modal auto-closes |
-| `maxItems`         | `number`                          |  | `1` = single (default), `>1` = multi up to cap |
-| `accept`           | `string`                          |  | Same `<input accept>` syntax — applies to upload **and** grid filter |
-| `title`            | `string`                          |  | Modal heading. Default `"Select media"` |
-| `description`      | `string`                          |  | Subheading under the title |
-| `open`             | `boolean`                         |  | Controlled open state |
-| `onOpenChange`     | `(open: boolean) => void`         |  | Controlled change handler |
-| `disabled`         | `boolean`                         |  | Trigger ignores clicks; visual disabled state |
-| `confirmLabel`     | `string`                          |  | Default `"Use selection"` |
-| `cancelLabel`      | `string`                          |  | Default `"Cancel"` |
-| `modalClassName`   | `string`                          |  | Class on the modal panel |
-| `triggerClassName` | `string`                          |  | Class on the trigger wrapper span |
-| …                  | rest of `MediaManagerProps`       |  | `bucketSlug`, `bucketFilter`, `showDetailsPane`, `classNames`, etc. forwarded to the inner `MediaManager` |
-
-The modal renders into `document.body` via `react-dom` portal, so it
-escapes parent `overflow:hidden` / transform stacking contexts. `Esc`
-closes; backdrop click closes; body scroll is locked while open.
-
-#### `Lightbox` (standalone)
-
-Exported separately so you can use it outside `MediaManager` (e.g. in
-a feed view):
-
-```tsx
-import { Lightbox } from "@sentroy-co/client-sdk/react"
-
-const [active, setActive] = useState<Media | null>(null)
-
-return (
-  <>
-    {/* …trigger… */}
-    {active && (
-      <Lightbox media={active} onClose={() => setActive(null)} />
-    )}
-  </>
-)
-```
-
-Image / video / audio rendered inline; everything else gets a download
-button. `Esc` closes, optional `onPrev` / `onNext` add ←/→ navigation.
-
-#### Helpers
-
-```ts
-import {
-  cn,           // tiny class joiner
-  formatBytes,  // 1234 → "1.21 KB"
-  detectKind,   // image | video | audio | pdf | doc | archive | code | other
-  matchAccept,  // matchAccept(file, "image/*,.pdf") → boolean
-  KIND_LABELS,
-  type MediaKind,
-} from "@sentroy-co/client-sdk/react"
-```
+Sections: [Quickstart](https://docs.sentroy.com) · [Mail](https://docs.sentroy.com/mail) · [Storage](https://docs.sentroy.com/storage) · [React](https://docs.sentroy.com/react) · [Tools](https://docs.sentroy.com/tools)
 
 ## Requirements
 
@@ -683,12 +131,12 @@ import {
 - React 18+ (only if you import from `/react`)
 - Tailwind CSS in the host app (only for React components)
 
-## Raw Documentation
+## For AI agents
 
-For AI agents and LLMs — plain-text version of this document:
+A single-file, comprehensive reference covering every endpoint, parameter and response shape lives at [`AGENTS.md`](AGENTS.md). Drop the raw URL into a context window:
 
 ```
-https://raw.githubusercontent.com/Sentroy-Co/client-sdk/refs/heads/main/typescript/README.md
+https://raw.githubusercontent.com/Sentroy-Co/client-sdk/refs/heads/main/typescript/AGENTS.md
 ```
 
 ## License