@sentroy-co/client-sdk 2.1.0 → 2.2.0

package/src/react/lib/Lightbox.tsx

@@ -0,0 +1,162 @@
+import { useEffect } from "react"
+import type { Media } from "../../types"
+import { detectKind, formatBytes } from "./utils"
+
+/**
+ * Sadeleştirilmiş lightbox — tek media item için fullscreen preview.
+ * Image/video native render, audio HTML5 player, diğerleri "download"
+ * fallback. ESC kapat, ←/→ next/prev (caller index callback'i sağlar).
+ *
+ * Headless yapı: tüm renderable HTML/inline class'lar default; consumer
+ * className override'ı ile değiştirebilir.
+ */
+export interface LightboxProps {
+  media: Media
+  onClose: () => void
+  onPrev?: () => void
+  onNext?: () => void
+  className?: string
+}
+
+export function Lightbox({
+  media,
+  onClose,
+  onPrev,
+  onNext,
+  className,
+}: LightboxProps) {
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") onClose()
+      if (e.key === "ArrowLeft" && onPrev) onPrev()
+      if (e.key === "ArrowRight" && onNext) onNext()
+    }
+    document.addEventListener("keydown", onKey)
+    document.body.style.overflow = "hidden"
+    return () => {
+      document.removeEventListener("keydown", onKey)
+      document.body.style.overflow = ""
+    }
+  }, [onClose, onPrev, onNext])
+
+  const kind = detectKind(media)
+  const url = media.url || media.downloadUrl
+
+  return (
+    <div
+      role="dialog"
+      aria-modal="true"
+      onClick={(e) => {
+        if (e.target === e.currentTarget) onClose()
+      }}
+      className={
+        className ||
+        "fixed inset-0 z-50 flex items-center justify-center bg-black/90 p-4 backdrop-blur-sm"
+      }
+    >
+      {/* Close button */}
+      <button
+        type="button"
+        onClick={onClose}
+        aria-label="Close"
+        className="absolute right-4 top-4 rounded-full bg-white/10 p-2 text-white transition-colors hover:bg-white/20"
+      >
+        <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+          <path d="M18 6L6 18M6 6l12 12" />
+        </svg>
+      </button>
+
+      {/* Prev */}
+      {onPrev && (
+        <button
+          type="button"
+          onClick={(e) => {
+            e.stopPropagation()
+            onPrev()
+          }}
+          aria-label="Previous"
+          className="absolute left-4 top-1/2 -translate-y-1/2 rounded-full bg-white/10 p-3 text-white transition-colors hover:bg-white/20"
+        >
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+            <path d="M15 18l-6-6 6-6" />
+          </svg>
+        </button>
+      )}
+
+      {/* Next */}
+      {onNext && (
+        <button
+          type="button"
+          onClick={(e) => {
+            e.stopPropagation()
+            onNext()
+          }}
+          aria-label="Next"
+          className="absolute right-4 top-1/2 -translate-y-1/2 rounded-full bg-white/10 p-3 text-white transition-colors hover:bg-white/20"
+        >
+          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+            <path d="M9 6l6 6-6 6" />
+          </svg>
+        </button>
+      )}
+
+      {/* Content */}
+      <div className="flex max-h-full max-w-5xl flex-col items-center gap-3">
+        {kind === "image" && url && (
+          // eslint-disable-next-line @next/next/no-img-element
+          <img
+            src={url}
+            alt={media.alt ?? media.fileName}
+            className="max-h-[80vh] max-w-full rounded-lg object-contain shadow-2xl"
+          />
+        )}
+        {kind === "video" && url && (
+          <video
+            src={url}
+            controls
+            autoPlay
+            className="max-h-[80vh] max-w-full rounded-lg shadow-2xl"
+          />
+        )}
+        {kind === "audio" && url && (
+          <div className="flex w-full max-w-md flex-col gap-3 rounded-lg bg-white/10 p-6 text-white">
+            <div className="text-center text-sm font-medium">
+              {media.fileName}
+            </div>
+            <audio src={url} controls className="w-full" />
+          </div>
+        )}
+        {kind !== "image" && kind !== "video" && kind !== "audio" && (
+          <div className="flex flex-col items-center gap-3 rounded-lg bg-white/10 p-8 text-white">
+            <svg width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5">
+              <path d="M14 2H6a2 2 0 00-2 2v16a2 2 0 002 2h12a2 2 0 002-2V8z" />
+              <path d="M14 2v6h6" />
+            </svg>
+            <div className="text-sm font-medium">{media.fileName}</div>
+            <a
+              href={url}
+              download={media.fileName}
+              target="_blank"
+              rel="noreferrer"
+              className="rounded-md bg-white px-4 py-2 text-xs font-semibold text-black hover:bg-white/90"
+            >
+              Download
+            </a>
+          </div>
+        )}
+
+        <div className="flex items-center gap-3 rounded-md bg-black/40 px-3 py-1.5 text-xs text-white/80">
+          <span className="font-mono truncate max-w-xs">{media.fileName}</span>
+          <span>·</span>
+          <span>{formatBytes(media.size ?? 0)}</span>
+          {media.mimeType && (
+            <>
+              <span>·</span>
+              <span className="font-mono opacity-70">{media.mimeType}</span>
+            </>
+          )}
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/react/lib/use-media-list.ts

@@ -0,0 +1,54 @@
+import { useCallback, useEffect, useState } from "react"
+import type { Sentroy } from "../.."
+import type { Media, MediaListResult } from "../../types"
+
+/**
+ * Bir bucket'taki media listesini çeken hook. Search, kind filter ve
+ * folder filter local-side; SDK'nın list endpoint'i şimdilik bunları
+ * server-side desteklemiyor (genelde 100-200 dosyalık küçük scale,
+ * client-side OK). Büyük scale'de paginate + server filter eklenir.
+ */
+export function useMediaList(args: {
+  client: Sentroy
+  bucketSlug: string | null
+  /** Yeniden tetiklenmek için artırılan key. */
+  refreshKey?: number
+}) {
+  const { client, bucketSlug, refreshKey = 0 } = args
+  const [data, setData] = useState<MediaListResult | null>(null)
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<string | null>(null)
+
+  useEffect(() => {
+    if (!bucketSlug) {
+      setData(null)
+      return
+    }
+    let cancelled = false
+    setLoading(true)
+    setError(null)
+    client.media
+      .list(bucketSlug, { limit: 200 })
+      .then((res) => {
+        if (cancelled) return
+        setData(res)
+      })
+      .catch((err: unknown) => {
+        if (cancelled) return
+        setError(err instanceof Error ? err.message : "Failed to load media")
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [client, bucketSlug, refreshKey])
+
+  const refresh = useCallback(() => {
+    // Caller kendi refreshKey'ini bump'lar; bu sadece convenience.
+    setData((d) => d)
+  }, [])
+
+  return { data, items: data?.items ?? ([] as Media[]), loading, error, refresh }
+}

package/src/react/lib/utils.ts

@@ -0,0 +1,73 @@
+/**
+ * Minimal class name combiner — clsx + twMerge gibi davranır ama
+ * dependency yok. Falsy filtrele, dedup yapma. Tema override'larında
+ * Tailwind utility çakışmaları için consumer kendi cn'ini kullanırsa
+ * `className` prop'u son geldiği için doğal şekilde kazanır.
+ */
+export function cn(
+  ...args: Array<string | undefined | null | false | 0>
+): string {
+  return args.filter(Boolean).join(" ")
+}
+
+export function formatBytes(bytes: number, decimals = 1): string {
+  if (!bytes) return "0 B"
+  const units = ["B", "KB", "MB", "GB", "TB"]
+  let i = 0
+  let v = bytes
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024
+    i++
+  }
+  return `${Number.isInteger(v) ? v : v.toFixed(decimals)} ${units[i]}`
+}
+
+/** İlk image-like extension veya MIME → "image", "video", "audio", "pdf",
+ *  "doc" (word/excel/ppt), "archive", "code", "other". */
+export function detectKind(file: {
+  mimeType?: string | null
+  fileName?: string
+}): MediaKind {
+  const mt = (file.mimeType ?? "").toLowerCase()
+  const ext = (file.fileName ?? "").split(".").pop()?.toLowerCase() ?? ""
+  if (mt.startsWith("image/")) return "image"
+  if (mt.startsWith("video/")) return "video"
+  if (mt.startsWith("audio/")) return "audio"
+  if (mt === "application/pdf" || ext === "pdf") return "pdf"
+  if (
+    /^(doc|docx|xls|xlsx|ppt|pptx|odt|ods|odp|txt|md|csv)$/.test(ext) ||
+    mt.startsWith("application/vnd.")
+  ) {
+    return "doc"
+  }
+  if (/^(zip|tar|gz|7z|rar|bz2)$/.test(ext)) return "archive"
+  if (
+    /^(js|ts|tsx|jsx|json|html|css|scss|sh|py|go|rb|php|rs|java|c|cpp)$/.test(
+      ext,
+    )
+  ) {
+    return "code"
+  }
+  return "other"
+}
+
+export type MediaKind =
+  | "image"
+  | "video"
+  | "audio"
+  | "pdf"
+  | "doc"
+  | "archive"
+  | "code"
+  | "other"
+
+export const KIND_LABELS: Record<MediaKind, string> = {
+  image: "Image",
+  video: "Video",
+  audio: "Audio",
+  pdf: "PDF",
+  doc: "Document",
+  archive: "Archive",
+  code: "Code",
+  other: "Other",
+}

package/src/resources/buckets.ts

@@ -0,0 +1,50 @@
+import type { HttpClient } from "../http"
+import type {
+  Bucket,
+  CreateBucketParams,
+  UpdateBucketParams,
+} from "../types"
+
+export class Buckets {
+  constructor(private http: HttpClient) {}
+
+  /** List all buckets in the company. */
+  async list(): Promise<Bucket[]> {
+    return this.http.get<Bucket[]>("/buckets")
+  }
+
+  /** Get a single bucket by its slug. */
+  async get(slug: string): Promise<Bucket> {
+    return this.http.get<Bucket>(`/buckets/${encodeURIComponent(slug)}`)
+  }
+
+  /** Create a new bucket. Slug is auto-derived from name if omitted. */
+  async create(params: CreateBucketParams): Promise<Bucket> {
+    return this.http.post<Bucket>("/buckets", params)
+  }
+
+  /**
+   * Update a bucket's name, description, or visibility. Toggling
+   * `isPublic` cascades to every existing file in the bucket (S3 ACL +
+   * Media doc); this call can take a while for large buckets.
+   */
+  async update(slug: string, params: UpdateBucketParams): Promise<Bucket> {
+    return this.http.patch<Bucket>(
+      `/buckets/${encodeURIComponent(slug)}`,
+      params,
+    )
+  }
+
+  /**
+   * Delete a bucket. Fails with 409 if the bucket has any files unless
+   * `force: true` is passed — then every file is purged from storage
+   * before the bucket is removed.
+   */
+  async delete(slug: string, opts?: { force?: boolean }): Promise<void> {
+    const query = opts?.force ? { force: "true" } : undefined
+    await this.http.del<{ deleted: boolean }>(
+      `/buckets/${encodeURIComponent(slug)}`,
+      query,
+    )
+  }
+}

package/src/resources/domains.ts

@@ -0,0 +1,16 @@
+import type { HttpClient } from "../http"
+import type { Domain } from "../types"
+
+export class Domains {
+  constructor(private http: HttpClient) {}
+
+  /** List all verified domains for the company */
+  async list(): Promise<Domain[]> {
+    return this.http.get<Domain[]>("/domains")
+  }
+
+  /** Get a single domain by ID */
+  async get(id: string): Promise<Domain> {
+    return this.http.get<Domain>(`/domains/${encodeURIComponent(id)}`)
+  }
+}

package/src/resources/inbox.ts

@@ -0,0 +1,99 @@
+import type { HttpClient } from "../http"
+import type {
+  MessageSummary,
+  MessageDetail,
+  Mailbox,
+  InboxListParams,
+} from "../types"
+
+export class Inbox {
+  constructor(private http: HttpClient) {}
+
+  /** List messages in a mailbox folder */
+  async list(params?: InboxListParams): Promise<MessageSummary[]> {
+    const query: Record<string, unknown> = {}
+    if (params?.mailbox) query.mailbox = params.mailbox
+    if (params?.folder) query.folder = params.folder
+    if (params?.page) query.page = params.page
+    if (params?.limit) query.limit = params.limit
+    if (params?.unreadOnly) query.unreadOnly = "true"
+    return this.http.get<MessageSummary[]>("/inbox", query)
+  }
+
+  /** Get a single message detail */
+  async get(
+    uid: number,
+    options?: { mailbox?: string; folder?: string },
+  ): Promise<MessageDetail> {
+    const query: Record<string, unknown> = {}
+    if (options?.mailbox) query.mailbox = options.mailbox
+    if (options?.folder) query.folder = options.folder
+    return this.http.get<MessageDetail>(`/inbox/${uid}`, query)
+  }
+
+  /** List IMAP folders (mailboxes) for a given email account */
+  async listFolders(mailbox?: string): Promise<Mailbox[]> {
+    const query: Record<string, unknown> = {}
+    if (mailbox) query.mailbox = mailbox
+    return this.http.get<Mailbox[]>("/inbox/mailboxes", query)
+  }
+
+  /** Get thread messages by subject */
+  async getThread(
+    subject: string,
+    mailbox?: string,
+  ): Promise<(MessageDetail & { folder: string })[]> {
+    const query: Record<string, unknown> = { subject }
+    if (mailbox) query.mailbox = mailbox
+    return this.http.get<(MessageDetail & { folder: string })[]>(
+      "/inbox/thread",
+      query,
+    )
+  }
+
+  /** Mark a message as read */
+  async markAsRead(
+    uid: number,
+    options?: { mailbox?: string; folder?: string },
+  ): Promise<void> {
+    await this.http.post(`/inbox/${uid}/read`, {
+      mailbox: options?.mailbox,
+      folder: options?.folder,
+    })
+  }
+
+  /** Mark a message as unread */
+  async markAsUnread(
+    uid: number,
+    options?: { mailbox?: string; folder?: string },
+  ): Promise<void> {
+    await this.http.del(`/inbox/${uid}/read`, {
+      mailbox: options?.mailbox,
+      folder: options?.folder,
+    })
+  }
+
+  /** Move a message to another folder */
+  async move(
+    uid: number,
+    to: string,
+    options?: { from?: string; mailbox?: string },
+  ): Promise<void> {
+    await this.http.post(`/inbox/${uid}/move`, {
+      to,
+      from: options?.from,
+      mailbox: options?.mailbox,
+    })
+  }
+
+  /** Delete a message */
+  async delete(
+    uid: number,
+    options?: { mailbox?: string; folder?: string },
+  ): Promise<void> {
+    const query: Record<string, unknown> = {}
+    if (options?.mailbox) query.mailbox = options.mailbox
+    if (options?.folder) query.folder = options.folder
+    await this.http.del(`/inbox/${uid}`, query)
+  }
+}

package/src/resources/mailboxes.ts

@@ -0,0 +1,11 @@
+import type { HttpClient } from "../http"
+import type { MailboxUser } from "../types"
+
+export class Mailboxes {
+  constructor(private http: HttpClient) {}
+
+  /** List all mailbox accounts for the company */
+  async list(): Promise<MailboxUser[]> {
+    return this.http.get<MailboxUser[]>("/mailboxes")
+  }
+}

package/src/resources/media.ts

@@ -0,0 +1,115 @@
+import type { HttpClient } from "../http"
+import type {
+  Media,
+  MediaListParams,
+  MediaListResult,
+  UploadMediaParams,
+} from "../types"
+
+export class MediaResource {
+  constructor(private http: HttpClient) {}
+
+  /** List files in a bucket (paginated). */
+  async list(
+    bucketSlug: string,
+    params?: MediaListParams,
+  ): Promise<MediaListResult> {
+    return this.http.get<MediaListResult>(
+      `/buckets/${encodeURIComponent(bucketSlug)}/media`,
+      params as Record<string, unknown> | undefined,
+    )
+  }
+
+  /** Get a single media record. */
+  async get(bucketSlug: string, mediaId: string): Promise<Media> {
+    return this.http.get<Media>(
+      `/buckets/${encodeURIComponent(bucketSlug)}/media/${encodeURIComponent(mediaId)}`,
+    )
+  }
+
+  /**
+   * Upload a file to a bucket. Works in Node and the browser: `body`
+   * is a `Blob` or `File`. Returns the full serialized media record
+   * (with `url`, `downloadUrl`, image thumbnails when applicable).
+   *
+   * @example Browser
+   * ```ts
+   * const file = input.files[0]
+   * const media = await sentroy.media.upload("my-bucket", { body: file })
+   * console.log(media.url)
+   * ```
+   *
+   * @example Node 18+
+   * ```ts
+   * import { openAsBlob } from "node:fs"
+   * const blob = await openAsBlob("./photo.jpg")
+   * const media = await sentroy.media.upload("my-bucket", {
+   *   body: blob,
+   *   filename: "photo.jpg",
+   * })
+   * ```
+   */
+  async upload(
+    bucketSlug: string,
+    params: UploadMediaParams,
+  ): Promise<Media> {
+    const form = new FormData()
+    const filename =
+      params.filename ||
+      (params.body as File & { name?: string }).name ||
+      "upload.bin"
+    form.append("file", params.body, filename)
+    if (params.folder) form.append("folder", params.folder)
+    if (params.isPublic !== undefined) {
+      form.append("public", params.isPublic ? "true" : "false")
+    }
+    if (params.alt) form.append("alt", params.alt)
+    if (params.caption) form.append("caption", params.caption)
+    if (params.tags?.length) form.append("tags", params.tags.join(","))
+
+    return this.http.postForm<Media>(
+      `/buckets/${encodeURIComponent(bucketSlug)}/media`,
+      form,
+    )
+  }
+
+  /**
+   * Delete a file. Cascades through the CDN: S3 objects (original +
+   * thumbnails) are removed, then the Media record. If any S3 delete
+   * fails the record is kept so you can retry.
+   */
+  async delete(bucketSlug: string, mediaId: string): Promise<void> {
+    await this.http.del<{ deleted: boolean }>(
+      `/buckets/${encodeURIComponent(bucketSlug)}/media/${encodeURIComponent(mediaId)}`,
+    )
+  }
+
+  /**
+   * Download a media file. For private buckets this is the only way to
+   * fetch the bytes since the CDN public URL won't serve them; the
+   * storage app proxies through after auth.
+   *
+   * Pass `quality` to request a pre-generated thumbnail variant (e.g.
+   * `quality: 500` for 500px wide). Falls back to the original if the
+   * variant doesn't exist for that file.
+   */
+  async download(
+    bucketSlug: string,
+    mediaId: string,
+    opts?: { quality?: number | "original" },
+  ): Promise<Blob> {
+    const quality = opts?.quality
+    const query =
+      quality && quality !== "original"
+        ? { quality: String(quality) }
+        : undefined
+    const res = await this.http.fetchRaw(
+      `/buckets/${encodeURIComponent(bucketSlug)}/media/${encodeURIComponent(mediaId)}/download`,
+      { query },
+    )
+    if (!res.ok) {
+      throw new Error(`Download failed with status ${res.status}`)
+    }
+    return res.blob()
+  }
+}

package/src/resources/send.ts

@@ -0,0 +1,11 @@
+import type { HttpClient } from "../http"
+import type { SendParams, SendResult } from "../types"
+
+export class Send {
+  constructor(private http: HttpClient) {}
+
+  /** Send an email */
+  async email(params: SendParams): Promise<SendResult> {
+    return this.http.post<SendResult>("/send", params)
+  }
+}

package/src/resources/storage.ts

@@ -0,0 +1,28 @@
+import type { HttpClient } from "../http"
+import type { StorageQuota, StorageUsage } from "../types"
+
+/**
+ * Storage observability — read-only quota + breakdown endpoints. Bucket
+ * and media CRUD lives on `client.buckets` / `client.media`.
+ */
+export class Storage {
+  constructor(private http: HttpClient) {}
+
+  /**
+   * Plan storage quota for the company. `used` reflects bucket totals,
+   * `mailUsed` what the mail product has stored under the same plan
+   * pool, and `limit: 0` means unlimited.
+   */
+  async quota(): Promise<StorageQuota> {
+    return this.http.get<StorageQuota>("/storage-quota")
+  }
+
+  /**
+   * Combined dashboard payload — plan quota + per-bucket byte/file
+   * counts + per-type aggregation across the company. Single round-trip
+   * intended for usage UIs.
+   */
+  async usage(): Promise<StorageUsage> {
+    return this.http.get<StorageUsage>("/usage")
+  }
+}

package/src/resources/templates.ts

@@ -0,0 +1,16 @@
+import type { HttpClient } from "../http"
+import type { Template } from "../types"
+
+export class Templates {
+  constructor(private http: HttpClient) {}
+
+  /** List all templates */
+  async list(): Promise<Template[]> {
+    return this.http.get<Template[]>("/templates")
+  }
+
+  /** Get a single template by ID */
+  async get(id: string): Promise<Template> {
+    return this.http.get<Template>(`/templates/${encodeURIComponent(id)}`)
+  }
+}