@sentroy-co/client-sdk 2.6.3 → 2.6.4

package/AGENTS.md

@@ -0,0 +1,692 @@
+<p align="center">
+  <img src="https://sentroy.com/business/sentroy-logo-light.png" alt="Sentroy" width="240" />
+</p>
+
+<h3 align="center">Sentroy Client SDK for TypeScript — Full Reference</h3>
+
+<p align="center">
+  Comprehensive single-file reference covering every resource, parameter, and response shape.<br />
+  Optimised for AI agents and LLMs — feed the raw URL of this file into a context window and the assistant has the complete API surface.
+</p>
+
+<p align="center">
+  <strong>Humans:</strong> start with the lean <a href="README.md">README</a> or browse <a href="https://docs.sentroy.com">docs.sentroy.com</a> for searchable, interactive docs.
+</p>
+
+---
+
+## Installation
+
+```bash
+npm install @sentroy-co/client-sdk
+```
+
+## Quick Start
+
+```ts
+import { Sentroy } from "@sentroy-co/client-sdk"
+
+const sentroy = new Sentroy({
+  baseUrl: "https://sentroy.com",
+  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" },
+})
+
+// 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",
+    },
+  ],
+})
+```
+
+### Buckets
+
+Storage is organized into **buckets** — isolated containers with their own
+visibility (public vs private) and usage counters.
+
+```ts
+// List all buckets in the company
+const buckets = await sentroy.buckets.list()
+
+// 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,
+})
+
+// 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 })
+```
+
+### 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)
+```
+
+#### Thumbnail URL helpers
+
+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:
+
+```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:
+
+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
+  }
+}
+```
+
+## 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"
+
+import { Sentroy } from "@sentroy-co/client-sdk"
+import { MediaManager } from "@sentroy-co/client-sdk/react"
+
+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)}
+    />
+  )
+}
+```
+
+#### 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`:
+
+```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`.
+
+When you migrate to a different theme system later, change tokens in
+one place — every Tailwind utility resolves through your `globals.css`.
+
+### `MediaManagerTrigger`
+
+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.
+
+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.
+
+```tsx
+"use client"
+
+import { Sentroy } from "@sentroy-co/client-sdk"
+import { MediaManagerTrigger } from "@sentroy-co/client-sdk/react"
+
+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)
+      }}
+    />
+  )
+}
+```
+
+#### 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"
+```
+
+## Requirements
+
+- Node.js 18+ (uses native `fetch`)
+- React 18+ (only if you import from `/react`)
+- Tailwind CSS in the host app (only for React components)
+
+## Raw URL — for LLM/agent context windows
+
+```
+https://raw.githubusercontent.com/Sentroy-Co/client-sdk/refs/heads/main/typescript/AGENTS.md
+```
+
+## License
+
+[MIT](LICENSE)