@sentroy-co/client-sdk 2.2.1 → 2.4.2

package/src/react/MediaManager.tsx

@@ -9,11 +9,13 @@ import type { Sentroy } from ".."
 import type { Bucket, Media } from "../types"
 import { Lightbox } from "./lib/Lightbox"
 import { useMediaList } from "./lib/use-media-list"
+import { pickPresetThumbnailUrl } from "../thumbnails"
 import {
   cn,
   detectKind,
   formatBytes,
   KIND_LABELS,
+  matchAccept,
   type MediaKind,
 } from "./lib/utils"
 
@@ -64,7 +66,19 @@ export interface MediaManagerProps {
   bucketSlug?: string
   /** Birden fazla seçilebilir mi? Default false. */
   multiple?: boolean
-  /** Yalnızca belirli MIME prefix'leri kabul et upload'ta — örn "image/*". */
+  /**
+   * Multi-mode'da cap. multiple=true iken cap'e ulaşılınca yeni seçim
+   * sessizce engellenir. multiple=false iken yok sayılır (single = 1).
+   * Default: undefined (cap yok).
+   */
+  maxItems?: number
+  /**
+   * Upload + grid filter için MIME pattern — örn `"image/*"`,
+   * `"image/png,image/jpeg"`, `"video/*,application/pdf"`.
+   * - Upload `<input type="file">` `accept` özniteliğine geçer.
+   * - Grid'de `accept` ile uyumlu olmayan item'lar gizlenir
+   *   (kullanıcı yine de bucket'ında görebilir ama picker'da seçemez).
+   */
   accept?: string
   /** Kullanıcının önceden seçtiği item'lar — Media obje ya da id string. */
   initialValue?: Array<Media | string>
@@ -102,6 +116,7 @@ export function MediaManager(props: MediaManagerProps) {
     client,
     bucketSlug: initialBucketSlug,
     multiple = false,
+    maxItems,
     accept,
     initialValue,
     onChange,
@@ -171,8 +186,16 @@ export function MediaManager(props: MediaManagerProps) {
       setSelectedIds((prev) => {
         const next = new Set(prev)
         if (multiple) {
-          if (next.has(media.id)) next.delete(media.id)
-          else next.add(media.id)
+          if (next.has(media.id)) {
+            next.delete(media.id)
+          } else {
+            // maxItems cap — multi-mode'da limite ulaşıldıysa yeni
+            // seçimi engelle (mevcut state'i değiştirmeden döndür).
+            if (typeof maxItems === "number" && next.size >= maxItems) {
+              return prev
+            }
+            next.add(media.id)
+          }
         } else {
           // Single: aynısı tıklanırsa deselect
           if (next.has(media.id) && next.size === 1) next.clear()
@@ -184,7 +207,7 @@ export function MediaManager(props: MediaManagerProps) {
         return next
       })
     },
-    [multiple],
+    [multiple, maxItems],
   )
 
   const selected = useMemo(
@@ -207,9 +230,10 @@ export function MediaManager(props: MediaManagerProps) {
     return items.filter((m) => {
       if (q && !m.fileName.toLowerCase().includes(q)) return false
       if (kindFilter !== "all" && detectKind(m) !== kindFilter) return false
+      if (accept && !matchAccept(m, accept)) return false
       return true
     })
-  }, [items, search, kindFilter])
+  }, [items, search, kindFilter, accept])
 
   // ── Upload ─────────────────────────────────────────────────────────────
   const fileInputRef = useRef<HTMLInputElement | null>(null)
@@ -412,8 +436,13 @@ export function MediaManager(props: MediaManagerProps) {
               {visibleItems.map((media) => {
                 const isSel = selectedIds.has(media.id)
                 const kind = detectKind(media)
+                // Grid card 200-300 px display — orijinal 4K JPG yerine
+                // "card" preset (~500px) thumbnail. Gerçek thumbnail yoksa
+                // helper orijinale fallback yapar.
                 const thumb =
-                  kind === "image" ? media.url || media.downloadUrl : null
+                  kind === "image"
+                    ? pickPresetThumbnailUrl(media, "card") ?? null
+                    : null
                 return (
                   <button
                     key={media.id}
@@ -517,10 +546,11 @@ export function MediaManager(props: MediaManagerProps) {
                 return (
                   <>
                     <div className="aspect-square overflow-hidden rounded-md bg-muted/30">
-                      {kind === "image" && (m.url || m.downloadUrl) ? (
+                      {kind === "image" &&
+                      pickPresetThumbnailUrl(m, "card") ? (
                         // eslint-disable-next-line @next/next/no-img-element
                         <img
-                          src={m.url || m.downloadUrl || ""}
+                          src={pickPresetThumbnailUrl(m, "card") ?? ""}
                           alt={m.alt ?? m.fileName}
                           className="size-full object-cover"
                         />

package/src/react/MediaManagerTrigger.tsx

@@ -0,0 +1,260 @@
+import { useCallback, useEffect, useState, type ReactNode } from "react"
+import { createPortal } from "react-dom"
+import type { Media } from "../types"
+import { MediaManager, type MediaManagerProps } from "./MediaManager"
+import { cn } from "./lib/utils"
+
+/**
+ * MediaManagerTrigger — herhangi bir consumer-defined öğe (button, avatar
+ * thumb, ikon, vb.) tıklandığında MediaManager'ı modal içinde açan
+ * sarmalayıcı.
+ *
+ * Tasarım hedefi: kullanıcı kendi tetikleyicisini (`trigger` prop) verir,
+ * tıklanma + modal yönetimi + confirm/cancel akışı SDK tarafında olur.
+ * Böylece consumer her seferinde Dialog state ve render boilerplate'ini
+ * yazmak zorunda kalmaz — sadece "şu butonum şu callback'i tetiklesin"
+ * kadar kısa olur.
+ *
+ * Modal Tailwind utility class kullanır (host app'in design token'ları)
+ * ve `react-dom` portal ile `<body>`'ye render edilir — parent
+ * overflow:hidden / transform stacking context'lerine takılmaz.
+ *
+ * @example
+ * ```tsx
+ * <MediaManagerTrigger
+ *   client={client}
+ *   trigger={<Button>Change avatar</Button>}
+ *   maxItems={1}
+ *   accept="image/*"
+ *   onSelect={(media) => console.log(media[0].url)}
+ * />
+ * ```
+ */
+
+export interface MediaManagerTriggerProps
+  extends Omit<MediaManagerProps, "onSelect" | "onChange" | "multiple"> {
+  /** Tıklanabilir herhangi bir öğe — button, image, div, vb. */
+  trigger: ReactNode
+  /**
+   * Maksimum seçilebilir item sayısı. 1 = single mode, >1 = multi up to
+   * cap. Default 1. Cap'e ulaşılınca yeni item seçimi sessizce engellenir.
+   */
+  maxItems?: number
+  /** Confirm — kullanıcı "Use selection" butonuna bastığında çağrılır. */
+  onSelect: (selected: Media[]) => void
+  /** Modal başlığı. Default "Select media". */
+  title?: string
+  /** Modal description satırı (opsiyonel). */
+  description?: string
+  /**
+   * Controlled mode — open state'ini parent yönetmek isterse.
+   * Default uncontrolled (kendi içinde useState).
+   */
+  open?: boolean
+  /** Controlled mode için open değişikliği callback'i. */
+  onOpenChange?: (open: boolean) => void
+  /** Modal panel class override. */
+  modalClassName?: string
+  /** Trigger wrapper class — default `inline-block cursor-pointer`. */
+  triggerClassName?: string
+  /** Confirm butonu metni. Default "Use selection". */
+  confirmLabel?: string
+  /** Cancel butonu metni. Default "Cancel". */
+  cancelLabel?: string
+  /** Trigger'ın disabled durumu — modal açılmaz. */
+  disabled?: boolean
+}
+
+export function MediaManagerTrigger(props: MediaManagerTriggerProps) {
+  const {
+    trigger,
+    maxItems = 1,
+    onSelect,
+    title = "Select media",
+    description,
+    open: controlledOpen,
+    onOpenChange,
+    modalClassName,
+    triggerClassName,
+    confirmLabel = "Use selection",
+    cancelLabel = "Cancel",
+    disabled = false,
+    ...mmProps
+  } = props
+
+  const [internalOpen, setInternalOpen] = useState(false)
+  const [selected, setSelected] = useState<Media[]>([])
+  const [mounted, setMounted] = useState(false)
+
+  // SSR guard — portal yalnızca client'ta.
+  useEffect(() => {
+    setMounted(true)
+  }, [])
+
+  const isControlled = controlledOpen !== undefined
+  const open = isControlled ? controlledOpen : internalOpen
+  const setOpen = useCallback(
+    (v: boolean) => {
+      if (!isControlled) setInternalOpen(v)
+      onOpenChange?.(v)
+      if (!v) setSelected([])
+    },
+    [isControlled, onOpenChange],
+  )
+
+  // ESC — modal'ı kapat.
+  useEffect(() => {
+    if (!open) return
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        e.preventDefault()
+        setOpen(false)
+      }
+    }
+    document.addEventListener("keydown", onKey)
+    return () => document.removeEventListener("keydown", onKey)
+  }, [open, setOpen])
+
+  // Body scroll lock — modal açıkken arka planda scroll olmasın.
+  useEffect(() => {
+    if (!open) return
+    const original = document.body.style.overflow
+    document.body.style.overflow = "hidden"
+    return () => {
+      document.body.style.overflow = original
+    }
+  }, [open])
+
+  const handleConfirm = useCallback(() => {
+    onSelect(selected)
+    setOpen(false)
+  }, [onSelect, selected, setOpen])
+
+  const handleTriggerClick = useCallback(() => {
+    if (disabled) return
+    setOpen(true)
+  }, [disabled, setOpen])
+
+  // Trigger — span'a click handler bağla. Consumer'ın trigger'ı zaten
+  // button olabilir; bu durumda nested button HTML invalid olur ama
+  // tarayıcılar tolere eder. İstenirse triggerClassName ile span yerine
+  // başka semantik kullanılabilir (consumer kendi trigger'ında onClick
+  // override edemez — modal handler'ı her zaman çalışır).
+  const triggerNode = (
+    <span
+      role="button"
+      tabIndex={disabled ? -1 : 0}
+      aria-haspopup="dialog"
+      aria-expanded={open}
+      aria-disabled={disabled}
+      onClick={handleTriggerClick}
+      onKeyDown={(e) => {
+        if (disabled) return
+        if (e.key === "Enter" || e.key === " ") {
+          e.preventDefault()
+          setOpen(true)
+        }
+      }}
+      className={cn(
+        "inline-block",
+        disabled ? "cursor-not-allowed opacity-50" : "cursor-pointer",
+        triggerClassName,
+      )}
+    >
+      {trigger}
+    </span>
+  )
+
+  const modalNode =
+    open && mounted ? (
+      <div
+        className="fixed inset-0 z-[100] flex items-center justify-center p-4"
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="sentroy-mm-title"
+      >
+        <div
+          className="absolute inset-0 bg-black/60 backdrop-blur-sm"
+          onClick={() => setOpen(false)}
+        />
+        <div
+          className={cn(
+            "relative z-10 flex h-[85vh] w-full max-w-5xl flex-col gap-3 rounded-xl border bg-background p-4 shadow-2xl",
+            modalClassName,
+          )}
+        >
+          <div className="flex items-start justify-between gap-2">
+            <div className="flex flex-col gap-0.5">
+              <h2 id="sentroy-mm-title" className="text-base font-semibold">
+                {title}
+              </h2>
+              {description && (
+                <p className="text-xs text-muted-foreground">{description}</p>
+              )}
+            </div>
+            <button
+              type="button"
+              onClick={() => setOpen(false)}
+              className="rounded-md p-1 text-muted-foreground hover:bg-muted/50"
+              aria-label="Close"
+            >
+              <svg
+                width="16"
+                height="16"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+              >
+                <path d="M18 6L6 18M6 6l12 12" />
+              </svg>
+            </button>
+          </div>
+          <div className="min-h-0 flex-1 overflow-hidden">
+            <MediaManager
+              {...mmProps}
+              multiple={maxItems > 1}
+              maxItems={maxItems}
+              onChange={setSelected}
+              className={cn("h-full", mmProps.className)}
+            />
+          </div>
+          <div className="flex items-center justify-between gap-2 border-t pt-3">
+            <div className="text-xs text-muted-foreground">
+              {selected.length === 0
+                ? maxItems === 1
+                  ? "Select an item"
+                  : `Select up to ${maxItems} items`
+                : maxItems === 1
+                  ? "1 item selected"
+                  : `${selected.length} / ${maxItems} selected`}
+            </div>
+            <div className="flex items-center gap-2">
+              <button
+                type="button"
+                onClick={() => setOpen(false)}
+                className="rounded-md border px-3 py-1.5 text-xs hover:bg-muted/50"
+              >
+                {cancelLabel}
+              </button>
+              <button
+                type="button"
+                onClick={handleConfirm}
+                disabled={selected.length === 0}
+                className="rounded-md bg-foreground px-3 py-1.5 text-xs font-medium text-background transition-opacity hover:opacity-90 disabled:opacity-50"
+              >
+                {confirmLabel}
+              </button>
+            </div>
+          </div>
+        </div>
+      </div>
+    ) : null
+
+  return (
+    <>
+      {triggerNode}
+      {mounted && modalNode ? createPortal(modalNode, document.body) : null}
+    </>
+  )
+}

package/src/react/index.ts

@@ -3,11 +3,16 @@ export {
   type MediaManagerProps,
   type MediaManagerClassNames,
 } from "./MediaManager"
+export {
+  MediaManagerTrigger,
+  type MediaManagerTriggerProps,
+} from "./MediaManagerTrigger"
 export { Lightbox, type LightboxProps } from "./lib/Lightbox"
 export {
   cn,
   formatBytes,
   detectKind,
+  matchAccept,
   KIND_LABELS,
   type MediaKind,
 } from "./lib/utils"

package/src/react/lib/Lightbox.tsx

@@ -1,5 +1,6 @@
 import { useEffect } from "react"
 import type { Media } from "../../types"
+import { pickPresetThumbnailUrl } from "../../thumbnails"
 import { detectKind, formatBytes } from "./utils"
 
 /**
@@ -40,7 +41,13 @@ export function Lightbox({
   }, [onClose, onPrev, onNext])
 
   const kind = detectKind(media)
-  const url = media.url || media.downloadUrl
+  // Lightbox modal — büyük preview ama 4K/orijinal gerekmez. Image
+  // için "preview" preset (~960px) kullan, video/audio/diğerlerinde
+  // orijinal URL'i akıt.
+  const url =
+    kind === "image"
+      ? pickPresetThumbnailUrl(media, "preview") ?? media.url ?? media.downloadUrl
+      : media.url ?? media.downloadUrl
 
   return (
     <div

package/src/react/lib/utils.ts

@@ -71,3 +71,37 @@ export const KIND_LABELS: Record<MediaKind, string> = {
   code: "Code",
   other: "Other",
 }
+
+/**
+ * `<input accept="...">` semantics — pattern listesi virgülle ayrılır,
+ * her parça:
+ *  - `image/*` → MIME wildcard (image/png, image/jpeg ✓)
+ *  - `image/png` → MIME exact match
+ *  - `.png` → file extension (case-insensitive)
+ *
+ * Hiçbir parça eşleşmezse false. Accept boş/undefined olursa caller
+ * filter'ı atlamalı — bu fonksiyon o yüzden boş string'i false döner.
+ */
+export function matchAccept(
+  file: { mimeType?: string | null; fileName?: string },
+  accept: string,
+): boolean {
+  const patterns = accept
+    .split(",")
+    .map((s) => s.trim().toLowerCase())
+    .filter(Boolean)
+  if (patterns.length === 0) return false
+  const mt = (file.mimeType ?? "").toLowerCase()
+  const fn = (file.fileName ?? "").toLowerCase()
+  for (const p of patterns) {
+    if (p.startsWith(".")) {
+      if (fn.endsWith(p)) return true
+    } else if (p.endsWith("/*")) {
+      const prefix = p.slice(0, -1) // "image/*" → "image/"
+      if (mt.startsWith(prefix)) return true
+    } else if (p === mt) {
+      return true
+    }
+  }
+  return false
+}

package/src/thumbnails.ts

@@ -0,0 +1,128 @@
+/**
+ * Media thumbnail URL helpers — display target'ına göre uygun boyutta
+ * URL döndürür. Orijinal kaliteyi avatar/grid card gibi küçük yerlerde
+ * göstermek bandwidth ve render cost açısından mantıksız.
+ *
+ * CDN tarafı upload sırasında image'lar için pre-generated thumbnail'lar
+ * üretir (`imageMeta.thumbnails[]`). Bu helper:
+ *  1. Hedef boyutu kapsayacak en küçük thumbnail'ı seçer (yoksa en büyük).
+ *  2. Thumbnail URL'i exposed ise direkt onu kullanır.
+ *  3. Değilse `media.url`'in CDN prefix'ine `thumbnail.fileName` ekleyerek
+ *     URL inşa eder ({cdn-base}/{bucketId}/{thumbnail.fileName}).
+ *  4. Hiçbir public URL yoksa download endpoint'ini `?quality=N` ile döner.
+ *  5. En kötü durumda media.downloadUrl ya da undefined.
+ */
+
+import type { Media, MediaThumbnail } from "./types"
+
+/**
+ * Yardımcı fonksiyona verilebilecek minimum Media subset — Media tipinin
+ * tamamını import etmek istemeyen consumer'lar için.
+ */
+export type ThumbnailSourceMedia = Pick<
+  Media,
+  "url" | "downloadUrl" | "imageMeta" | "type"
+>
+
+/**
+ * Display hedef boyutuna göre uygun thumbnail URL'sini döndür.
+ *
+ * @param media     Sentroy media object (list / get / upload result).
+ * @param targetPx  Display'in maksimum boyutu (genişlik veya yükseklik) px.
+ *                  Retina için `2x` ile çağırın: `pickThumbnailUrl(m, 56*2)`.
+ *
+ * @returns         URL string ya da hiçbir şey üretilemezse `undefined`.
+ *
+ * @example
+ * ```tsx
+ * const avatarUrl = pickThumbnailUrl(media, 56 * 2) // 112px target
+ * <img src={avatarUrl} className="size-14 rounded-full" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * const cardUrl = pickThumbnailUrl(media, 320)
+ * const fullUrl = media.url // grid'te küçük, lightbox'ta orijinal
+ * ```
+ */
+export function pickThumbnailUrl(
+  media: ThumbnailSourceMedia,
+  targetPx: number,
+): string | undefined {
+  // Image değilse veya thumbnail listesi boşsa — orijinal URL.
+  const thumbs = media.imageMeta?.thumbnails
+  if (!thumbs || thumbs.length === 0 || media.type !== "image") {
+    return media.url ?? media.downloadUrl
+  }
+  if (!targetPx || targetPx <= 0) {
+    return media.url ?? media.downloadUrl
+  }
+
+  // En yakın "kapsayan" thumbnail — width >= target olan en küçük; yoksa
+  // en büyük (target'tan küçük olsa bile en az bozulmayı verir).
+  const sorted = [...thumbs].sort((a, b) => a.width - b.width)
+  const fit =
+    sorted.find((t) => t.width >= targetPx) ?? sorted[sorted.length - 1]
+
+  // Backend bazı endpoint'lerde thumbnail'ın kendi URL'ini de döndüyor
+  // (CdnUploadResult.imageMeta.thumbnails[].url). Tipte opsiyonel olarak
+  // değil ama runtime'da gelirse direkt kullanırız.
+  const fitWithUrl = fit as MediaThumbnail & { url?: string }
+  if (typeof fitWithUrl.url === "string" && fitWithUrl.url.length > 0) {
+    return fitWithUrl.url
+  }
+
+  // Pattern fallback: original URL'in son `/`'ından sonraki kısmı atıp
+  // thumbnail'ın fileName'ini ekle. Backend pattern'ı:
+  //   {cdn}/{bucketId}/{originalFileName}     ← media.url
+  //   {cdn}/{bucketId}/{thumbnailFileName}    ← inşa edilen
+  if (media.url) {
+    const slash = media.url.lastIndexOf("/")
+    if (slash >= 0) {
+      // Query string varsa düşür — thumbnail için anlamsız.
+      const base = media.url.substring(0, slash + 1)
+      const cleanBase = base.split("?")[0]
+      return cleanBase + fit.fileName
+    }
+  }
+
+  // Public URL hiç yoksa proxy download endpoint'ini quality=N ile çağır.
+  if (media.downloadUrl) {
+    const sep = media.downloadUrl.includes("?") ? "&" : "?"
+    return `${media.downloadUrl}${sep}quality=${fit.width}`
+  }
+
+  return undefined
+}
+
+/**
+ * Yaygın preset boyutları — semantik isimle çağırmak isteyen consumer
+ * için kısayol. Retina-aware: avatar ufacık olduğundan @2x; orta boy
+ * preview için orijinal yerine ~640.
+ *
+ * Manuel `targetPx` vermek istemediğinde:
+ * `pickPresetThumbnailUrl(media, "avatar")`.
+ */
+export const THUMBNAIL_PRESETS = {
+  /** Avatar / round chip — 28-64px display, 2x retina için ~120 hedef. */
+  avatar: 128,
+  /** List/grid card — 200-300px display, ~500 hedef. */
+  card: 500,
+  /** Modal preview — büyük ama orijinali yormayan ~960. */
+  preview: 960,
+  /** Hero / fullbleed — 1280-1920 display, neredeyse orijinal. */
+  hero: 1600,
+} as const
+
+export type ThumbnailPreset = keyof typeof THUMBNAIL_PRESETS
+
+/**
+ * `pickThumbnailUrl`'in semantik kısayolu — display amacını isimle ifade
+ * et, helper preset → px mapping'ini halletsin.
+ */
+export function pickPresetThumbnailUrl(
+  media: ThumbnailSourceMedia,
+  preset: ThumbnailPreset,
+): string | undefined {
+  return pickThumbnailUrl(media, THUMBNAIL_PRESETS[preset])
+}

package/src/types.ts

@@ -12,8 +12,16 @@ export interface SentroyClientConfig {
   baseUrl: string
   /** Company slug */
   companySlug: string
-  /** Access token (stk_...). Same token works for mail + storage. */
-  accessToken: string
+  /**
+   * Access token (`stk_...`). Same token works for mail + storage.
+   *
+   * Optional: when omitted, the client uses **cookie auth**
+   * (`credentials: "include"` on every fetch) — useful for browser code
+   * running inside the Sentroy site itself, where the user's session
+   * cookie is already valid against `sentroy.com`. End users never have
+   * to paste an API key when the SDK is embedded in our own UI.
+   */
+  accessToken?: string
   /** Request timeout in milliseconds (default: 30000) */
   timeout?: number
 }