@lumibase/sdk 0.19.0 → 0.21.0

package/dist/index.cjs

@@ -27,9 +27,11 @@ __export(index_exports, {
   checkCdcPipelineHealth: () => checkCdcPipelineHealth,
   createAgentArtifact: () => createAgentArtifact,
   createAgentGoal: () => createAgentGoal,
+  createBookmark: () => createBookmark,
   createCdcPipeline: () => createCdcPipeline,
   createLumiClient: () => createLumiClient,
   decideAgentApproval: () => decideAgentApproval,
+  deleteBookmark: () => deleteBookmark,
   deleteCdcPipeline: () => deleteCdcPipeline,
   deployCdc: () => deployCdc,
   dryRunAccessImport: () => dryRunAccessImport,
@@ -38,6 +40,7 @@ __export(index_exports, {
   extractSeo: () => extractSeo,
   generateAgentApp: () => generateAgentApp,
   generateTypes: () => generateTypes,
+  getEffectivePreset: () => getEffectivePreset,
   graphql: () => graphql,
   importAccessManifest: () => importAccessManifest,
   jsonLdScript: () => jsonLdScript,
@@ -47,7 +50,9 @@ __export(index_exports, {
   listAgentGoals: () => listAgentGoals,
   listAgentRuns: () => listAgentRuns,
   listAgentTools: () => listAgentTools,
+  listBookmarks: () => listBookmarks,
   listCdcPipelines: () => listCdcPipelines,
+  mediaUrl: () => mediaUrl,
   publishAgentArtifact: () => publishAgentArtifact,
   readAgentMemoryContext: () => readAgentMemoryContext,
   readCdcPipeline: () => readCdcPipeline,
@@ -58,10 +63,12 @@ __export(index_exports, {
   retryAgentRun: () => retryAgentRun,
   rollbackAgentArtifact: () => rollbackAgentArtifact,
   rollbackCdcDeployment: () => rollbackCdcDeployment,
+  saveUserView: () => saveUserView,
   search: () => search,
   startCdcPipeline: () => startCdcPipeline,
   stopCdcPipeline: () => stopCdcPipeline,
   toNextMetadata: () => toNextMetadata,
+  updateBookmark: () => updateBookmark,
   updateCdcPipeline: () => updateCdcPipeline,
   validateCdcDeploymentEnv: () => validateCdcDeploymentEnv,
   writeAgentMemory: () => writeAgentMemory
@@ -104,12 +111,52 @@ function toErrorBody(status, body) {
 function createLumiClient(opts) {
   const fetcher = opts.fetcher ?? globalThis.fetch;
   const base = opts.url.replace(/\/$/, "");
-  async function rawRequest(path, init = {}) {
+  let currentToken = opts.token;
+  let currentRefreshToken = opts.refreshToken;
+  let refreshInFlight = null;
+  async function attemptRefresh() {
+    if (!currentRefreshToken) return false;
+    if (!refreshInFlight) {
+      refreshInFlight = (async () => {
+        try {
+          const res = await fetcher(`${base}/api/v1/auth/refresh`, {
+            method: "POST",
+            headers: {
+              "content-type": "application/json",
+              "x-lumi-site": opts.siteId
+            },
+            // Body transport is CSRF-exempt (the token isn't ambient).
+            body: JSON.stringify({ refreshToken: currentRefreshToken })
+          });
+          if (!res.ok) return false;
+          const data = parseResponseBody(await res.text())?.data;
+          if (!data?.token || !data.refreshToken) return false;
+          currentToken = data.token;
+          currentRefreshToken = data.refreshToken;
+          try {
+            opts.onTokensRefreshed?.({
+              token: data.token,
+              refreshToken: data.refreshToken,
+              refreshTokenExpiresAt: data.refreshTokenExpiresAt
+            });
+          } catch {
+          }
+          return true;
+        } catch {
+          return false;
+        } finally {
+          refreshInFlight = null;
+        }
+      })();
+    }
+    return refreshInFlight;
+  }
+  async function rawRequest(path, init = {}, retried = false) {
     const headers = new Headers(init.headers);
     for (const [key, value] of Object.entries(opts.headers ?? {})) {
       headers.set(key, value);
     }
-    headers.set("authorization", `Bearer ${opts.token}`);
+    headers.set("authorization", `Bearer ${currentToken}`);
     headers.set("x-lumi-site", opts.siteId);
     if (!headers.has("content-type") && init.body) {
       headers.set("content-type", "application/json");
@@ -118,6 +165,11 @@ function createLumiClient(opts) {
     const text = await res.text();
     const body = parseResponseBody(text);
     if (!res.ok) {
+      if (res.status === 401 && !retried && currentRefreshToken && path !== "/api/v1/auth/refresh") {
+        if (await attemptRefresh()) {
+          return rawRequest(path, init, true);
+        }
+      }
       if (res.status === 401 && opts.onUnauthorized) {
         try {
           opts.onUnauthorized();
@@ -130,7 +182,9 @@ function createLumiClient(opts) {
   }
   const baseClient = {
     url: opts.url,
-    token: opts.token,
+    get token() {
+      return currentToken;
+    },
     siteId: opts.siteId,
     fetcher,
     rawRequest,
@@ -1118,6 +1172,79 @@ function legacyRest() {
   };
 }
 
+// src/rest/gaps.ts
+function getEffectivePreset(collection) {
+  return async (client) => {
+    const res = await client.rawRequest(
+      `/api/v1/presets/effective?collection=${encodeURIComponent(collection)}`
+    );
+    return res.data;
+  };
+}
+function listBookmarks(collection) {
+  return async (client) => {
+    const res = await client.rawRequest(
+      `/api/v1/presets/bookmarks?collection=${encodeURIComponent(collection)}`
+    );
+    return res.data;
+  };
+}
+function saveUserView(input) {
+  return async (client) => {
+    const res = await client.rawRequest("/api/v1/presets", {
+      method: "POST",
+      body: JSON.stringify({ ...input, bookmark: null })
+    });
+    return res.data;
+  };
+}
+function createBookmark(input) {
+  return async (client) => {
+    const res = await client.rawRequest("/api/v1/presets", {
+      method: "POST",
+      body: JSON.stringify(input)
+    });
+    return res.data;
+  };
+}
+function updateBookmark(id, input) {
+  return async (client) => {
+    const res = await client.rawRequest(`/api/v1/presets/${encodeURIComponent(id)}`, {
+      method: "PATCH",
+      body: JSON.stringify(input)
+    });
+    return res.data;
+  };
+}
+function deleteBookmark(id) {
+  return async (client) => {
+    const res = await client.rawRequest(`/api/v1/presets/${encodeURIComponent(id)}`, {
+      method: "DELETE"
+    });
+    return res.data;
+  };
+}
+function mediaUrl(key, transform, opts) {
+  return (client) => {
+    const base = client.url.replace(/\/$/, "");
+    const path = `/api/v1/media/${key.split("/").map(encodeURIComponent).join("/")}`;
+    if (!transform) return `${base}${path}`;
+    const qs = new URLSearchParams();
+    if ("preset" in transform) {
+      qs.set("preset", transform.preset);
+    } else {
+      if (transform.width !== void 0) qs.set("width", String(transform.width));
+      if (transform.height !== void 0) qs.set("height", String(transform.height));
+      if (transform.format) qs.set("format", transform.format);
+      if (transform.quality !== void 0) qs.set("quality", String(transform.quality));
+      if (transform.fit) qs.set("fit", transform.fit);
+      if (opts?.sign) qs.set("sig", opts.sign);
+    }
+    const query = qs.toString();
+    return query ? `${base}${path}?${query}` : `${base}${path}`;
+  };
+}
+
 // src/rest/index.ts
 function search(query, params) {
   return async (client) => {
@@ -1141,6 +1268,7 @@ function readItems(collection, params) {
     if (params?.limit !== void 0) qs.set("limit", String(params.limit));
     if (params?.offset !== void 0) qs.set("offset", String(params.offset));
     if (params?.status) qs.set("status", params.status);
+    if (params?.meta) qs.set("meta", params.meta);
     const s = qs.toString();
     const query = s ? `?${s}` : "";
     const res = await client.rawRequest(`/api/v1/items/${collection}${query}`);
@@ -1592,9 +1720,11 @@ function jsonLdScript(item) {
   checkCdcPipelineHealth,
   createAgentArtifact,
   createAgentGoal,
+  createBookmark,
   createCdcPipeline,
   createLumiClient,
   decideAgentApproval,
+  deleteBookmark,
   deleteCdcPipeline,
   deployCdc,
   dryRunAccessImport,
@@ -1603,6 +1733,7 @@ function jsonLdScript(item) {
   extractSeo,
   generateAgentApp,
   generateTypes,
+  getEffectivePreset,
   graphql,
   importAccessManifest,
   jsonLdScript,
@@ -1612,7 +1743,9 @@ function jsonLdScript(item) {
   listAgentGoals,
   listAgentRuns,
   listAgentTools,
+  listBookmarks,
   listCdcPipelines,
+  mediaUrl,
   publishAgentArtifact,
   readAgentMemoryContext,
   readCdcPipeline,
@@ -1623,10 +1756,12 @@ function jsonLdScript(item) {
   retryAgentRun,
   rollbackAgentArtifact,
   rollbackCdcDeployment,
+  saveUserView,
   search,
   startCdcPipeline,
   stopCdcPipeline,
   toNextMetadata,
+  updateBookmark,
   updateCdcPipeline,
   validateCdcDeploymentEnv,
   writeAgentMemory

package/dist/index.d.cts

@@ -377,6 +377,12 @@ interface ListItemsParams {
     limit?: number;
     offset?: number;
     status?: string | null;
+    /**
+     * Controls whether the server computes the `count(*)` total. `'total_count'`
+     * (default) returns `meta.total`; `'none'` skips the extra aggregate query
+     * for a cheaper list (e.g. infinite scroll) and omits `meta.total`.
+     */
+    meta?: 'total_count' | 'none';
 }
 /** Reserved metadata attributes present on every search hit. */
 interface SearchHitMeta {
@@ -1365,8 +1371,29 @@ interface LumiClientOptions {
      * is thrown so a host (e.g. Studio) can clear the stale token and route
      * the operator back to the login screen. Errors thrown by the callback
      * are swallowed so they never mask the original `LumiError`.
+     *
+     * When auto-refresh is enabled (see `refreshToken`), `onUnauthorized`
+     * fires only AFTER a refresh attempt has also failed.
      */
     onUnauthorized?: () => void;
+    /**
+     * Rotating refresh token (body transport). When set, a `401` triggers a
+     * single `POST /api/v1/auth/refresh` with this token; on success the new
+     * access token is adopted and the original request is retried once. The
+     * refresh token rotates each call, so the new pair is surfaced via
+     * {@link onTokensRefreshed} for the host to persist. Omit to keep the
+     * legacy behaviour (no retry; `onUnauthorized` fires immediately).
+     */
+    refreshToken?: string;
+    /**
+     * Called after a successful silent refresh with the rotated token pair so
+     * the host can persist them (the old refresh token is now revoked).
+     */
+    onTokensRefreshed?: (tokens: {
+        token: string;
+        refreshToken: string;
+        refreshTokenExpiresAt?: string;
+    }) => void;
 }
 interface LumiResponse<T> {
     data: T;
@@ -1997,6 +2024,66 @@ declare function legacyRest(): <TSchema extends DefaultSchema>(client: LumiClien
     request: <T>(path: string, init?: RequestInit) => Promise<LumiResponse<T>>;
 };
 
+/**
+ * SDK commands for view presets (presets-inheritance) and media transform URLs
+ * (image-transform-dsl). Each is a command factory `(client) => Promise<T>`
+ * used with `client.request(...)`, matching the rest of the REST module.
+ *
+ * Content-version and translation-memory helpers live in the core SDK
+ * (`client.items(...).versions` and `client.tm`).
+ */
+
+type PresetScope = "user" | "role" | "global";
+interface ViewPreset {
+    id: string;
+    bookmark: string | null;
+    collection: string;
+    userId: string | null;
+    roleId: string | null;
+    layout: string;
+    layoutQuery: Record<string, unknown>;
+    layoutOptions: Record<string, unknown>;
+    search: string | null;
+    filter: Record<string, unknown>;
+    icon: string | null;
+    color: string | null;
+    refreshInterval: number;
+}
+interface ScopedViewPreset extends ViewPreset {
+    sourceScope: PresetScope;
+    roleDistance?: number;
+}
+declare function getEffectivePreset(collection: string): (client: LumiClient) => Promise<ScopedViewPreset | null>;
+declare function listBookmarks(collection: string): (client: LumiClient) => Promise<ScopedViewPreset[]>;
+/** Save (or overwrite) the acting user's default view for a collection. */
+declare function saveUserView(input: Partial<ViewPreset> & {
+    collection: string;
+}): (client: LumiClient) => Promise<ViewPreset>;
+declare function createBookmark(input: Partial<ViewPreset> & {
+    collection: string;
+    bookmark: string;
+}): (client: LumiClient) => Promise<ViewPreset>;
+declare function updateBookmark(id: string, input: Partial<ViewPreset>): (client: LumiClient) => Promise<ViewPreset>;
+declare function deleteBookmark(id: string): (client: LumiClient) => Promise<null>;
+interface MediaTransform {
+    width?: number;
+    height?: number;
+    format?: "webp" | "avif" | "jpeg" | "png";
+    quality?: number;
+    fit?: "cover" | "contain" | "fill" | "inside" | "outside";
+}
+/**
+ * Build a delivery URL for a media asset, optionally with a transform. Pass a
+ * `MediaTransform` for inline params, or `{ preset }` to reference a named
+ * server-side preset. Returns a path relative to the API base — the SDK client
+ * resolves it against its configured URL.
+ */
+declare function mediaUrl(key: string, transform?: MediaTransform | {
+    preset: string;
+}, opts?: {
+    sign?: string;
+}): (client: LumiClient) => string;
+
 /**
  * Full-text search via `GET /api/v1/search`. Omit `params.collection` for a
  * cross-collection (global) search that fans out over every collection of the
@@ -2129,4 +2216,4 @@ declare function toNextMetadata(item: unknown): Record<string, unknown>;
  */
 declare function jsonLdScript(item: unknown): string | undefined;
 
-export { ACCESS_EXPORT_SCHEMA, type AIApproval, type AIApprovalStatus, type AIChatResponse, type AIChatStatus, type AIContentAssistResult, type AIConversation, type AIFieldSuggestion, type AIMessage, type AccessConflict, type AccessConflictCheckInput, type AccessConflictReport, type AccessExportApiKey, type AccessExportBindings, type AccessExportManifest, type AccessExportPermission, type AccessExportPolicy, type AccessExportRole, type AccessImportApplyResult, type AccessImportDiff, type AccessImportDiffEntry, type AccessImportDiffSection, type AccessImportDryRunResult, type AccessImportIssue, type AccessImportMode, type AccessImportOptions, type AccessImportSummary, type ActivityResource, type AgentApprovalResource, type AgentArtifactCreateInput, type AgentArtifactResource, type AgentArtifactType, type AgentEvaluationResource, type AgentGenerateAppInput, type AgentGenerateAppResult, type AgentGoalCreateInput, type AgentGoalResource, type AgentMemoryContext, type AgentMemoryResource, type AgentMemoryWriteInput, type AgentRiskLevel, type AgentRunResource, type AgentToolResource, type ApiKeyCreateInput, type ApiKeyPolicyAttachment, type ApiKeyResource, type ApiKeyRoleAttachment, type ApiKeyRotateInput, type ApiKeySecretResult, AudienceClient, type AudienceClientOptions, type AudienceEvent, type AudienceNotification, type Brand, type CdcConnectorType, type CdcDeployInput, type CdcDeploymentResult, type CdcDeploymentStatus, type CdcDeploymentStep, type CdcDeploymentTarget, type CdcEnvValidationResult, type CdcHealthCheckResult, type CdcHealthMetricEntry, type CdcPipelineCreateInput, type CdcPipelineMetrics, type CdcPipelinePatchInput, type CdcPipelineResource, type CdcPipelineStatus, type CdcRollbackResult, type CdcValidateEnvInput, type ChannelEventCallback, type CollectionInput, type CollectionResource, type CompiledPermission, type ConnectionStatus, type ContentVersion, type CreateSCIMTokenParams, type DefaultSchema, type DeliverySeo, type DeploymentResource, type DeploymentTargetResource, type DomainCreateInput, type DomainResource, type DomainVerificationRecord, type ExtensionResource, type FieldDeleteOptions, type FieldInput, type FieldMutationOptions, type FieldRenameInput, type FieldResource, type FileResource, type FlowGraph, type FlowNode, type FlowResource, type FlowRun, type FlowRunResult, type FlowRunStatus, type FlowStatus, type FlowTriggerType, type FolderResource, type GenerateOptions, type GraphQLExtension, type ID, type ItemFilter, type ItemFilterOp, type ItemRow, type ListItemsParams, type ListItemsResponse, type ListMarketplaceExtensionsParams, type Locale, type LumiClient, type LumiClientOptions, LumiError, type LumiErrorBody, type LumiResponse, type MarketplaceExtension, type MarketplaceListResponse, type MaterializeDataResponse, type MaterializeProjection, type MaterializeRefreshResult, type MaterializeRefreshStrategy, type MaterializedCollection, type NotificationCallback, type PermissionAction, type PermissionBundle, type PermissionCheckResult, type PermissionRow, type PolicyDetail, type PolicyResource, type PresenceCallback, type PresenceEntry, type PresetResource, type PrimaryKeyType, RealtimeClient, type RealtimeEvent, type RealtimeEventCallback, type RelationInput, type RelationResource, type RelationType, type RevisionRow, type RoleDetail, type RoleResource, type SCIMTokenCreated, type SCIMTokenMeta, type SCIMTokenRotated, type SchemaApplyInput, type SchemaApplyResult, type SchemaChangedEvent, type SchemaDiff, type SchemaDiffEntry, type SchemaDiffInput, type SchemaDiffRisk, type SchemaRuntimeImpact, type SearchHit, type SearchHitMeta, type SearchParams, type SearchResponse, type SettingResource, type ShareCreateInput, type ShareResource, type ShareSecretResult, type SiteConfigUpdate, type SiteResource, type StatusCallback, type StorageMode, type TeamMemberResource, type TeamResource, type TmEntry, type TmSource, type TmSuggestion, type TranslationResource, type TypegenCollection, type TypegenField, type TypegenManifest, type TypegenRelation, type TypegenSchemaFilters, type UploadConfigResource, type UploadTypeCatalogueEntry, type UserPreferencesPayload, type UserResource, type VersionCompare, type VersionFieldChange, type WebSocketFactory, type WebSocketLike, type WebhookResource, checkCdcPipelineHealth, createAgentArtifact, createAgentGoal, createCdcPipeline, createLumiClient, decideAgentApproval, deleteCdcPipeline, deployCdc, dryRunAccessImport, evaluateAgentArtifact, exportAccessManifest, extractSeo, generateAgentApp, generateTypes, graphql, importAccessManifest, jsonLdScript, legacyRest, listAgentApprovals, listAgentArtifacts, listAgentGoals, listAgentRuns, listAgentTools, listCdcPipelines, publishAgentArtifact, readAgentMemoryContext, readCdcPipeline, readCdcPipelineMetricHistory, readCdcPipelineMetrics, readItem, readItems, retryAgentRun, rollbackAgentArtifact, rollbackCdcDeployment, search, startCdcPipeline, stopCdcPipeline, toNextMetadata, updateCdcPipeline, validateCdcDeploymentEnv, writeAgentMemory };
+export { ACCESS_EXPORT_SCHEMA, type AIApproval, type AIApprovalStatus, type AIChatResponse, type AIChatStatus, type AIContentAssistResult, type AIConversation, type AIFieldSuggestion, type AIMessage, type AccessConflict, type AccessConflictCheckInput, type AccessConflictReport, type AccessExportApiKey, type AccessExportBindings, type AccessExportManifest, type AccessExportPermission, type AccessExportPolicy, type AccessExportRole, type AccessImportApplyResult, type AccessImportDiff, type AccessImportDiffEntry, type AccessImportDiffSection, type AccessImportDryRunResult, type AccessImportIssue, type AccessImportMode, type AccessImportOptions, type AccessImportSummary, type ActivityResource, type AgentApprovalResource, type AgentArtifactCreateInput, type AgentArtifactResource, type AgentArtifactType, type AgentEvaluationResource, type AgentGenerateAppInput, type AgentGenerateAppResult, type AgentGoalCreateInput, type AgentGoalResource, type AgentMemoryContext, type AgentMemoryResource, type AgentMemoryWriteInput, type AgentRiskLevel, type AgentRunResource, type AgentToolResource, type ApiKeyCreateInput, type ApiKeyPolicyAttachment, type ApiKeyResource, type ApiKeyRoleAttachment, type ApiKeyRotateInput, type ApiKeySecretResult, AudienceClient, type AudienceClientOptions, type AudienceEvent, type AudienceNotification, type Brand, type CdcConnectorType, type CdcDeployInput, type CdcDeploymentResult, type CdcDeploymentStatus, type CdcDeploymentStep, type CdcDeploymentTarget, type CdcEnvValidationResult, type CdcHealthCheckResult, type CdcHealthMetricEntry, type CdcPipelineCreateInput, type CdcPipelineMetrics, type CdcPipelinePatchInput, type CdcPipelineResource, type CdcPipelineStatus, type CdcRollbackResult, type CdcValidateEnvInput, type ChannelEventCallback, type CollectionInput, type CollectionResource, type CompiledPermission, type ConnectionStatus, type ContentVersion, type CreateSCIMTokenParams, type DefaultSchema, type DeliverySeo, type DeploymentResource, type DeploymentTargetResource, type DomainCreateInput, type DomainResource, type DomainVerificationRecord, type ExtensionResource, type FieldDeleteOptions, type FieldInput, type FieldMutationOptions, type FieldRenameInput, type FieldResource, type FileResource, type FlowGraph, type FlowNode, type FlowResource, type FlowRun, type FlowRunResult, type FlowRunStatus, type FlowStatus, type FlowTriggerType, type FolderResource, type GenerateOptions, type GraphQLExtension, type ID, type ItemFilter, type ItemFilterOp, type ItemRow, type ListItemsParams, type ListItemsResponse, type ListMarketplaceExtensionsParams, type Locale, type LumiClient, type LumiClientOptions, LumiError, type LumiErrorBody, type LumiResponse, type MarketplaceExtension, type MarketplaceListResponse, type MaterializeDataResponse, type MaterializeProjection, type MaterializeRefreshResult, type MaterializeRefreshStrategy, type MaterializedCollection, type MediaTransform, type NotificationCallback, type PermissionAction, type PermissionBundle, type PermissionCheckResult, type PermissionRow, type PolicyDetail, type PolicyResource, type PresenceCallback, type PresenceEntry, type PresetResource, type PresetScope, type PrimaryKeyType, RealtimeClient, type RealtimeEvent, type RealtimeEventCallback, type RelationInput, type RelationResource, type RelationType, type RevisionRow, type RoleDetail, type RoleResource, type SCIMTokenCreated, type SCIMTokenMeta, type SCIMTokenRotated, type SchemaApplyInput, type SchemaApplyResult, type SchemaChangedEvent, type SchemaDiff, type SchemaDiffEntry, type SchemaDiffInput, type SchemaDiffRisk, type SchemaRuntimeImpact, type ScopedViewPreset, type SearchHit, type SearchHitMeta, type SearchParams, type SearchResponse, type SettingResource, type ShareCreateInput, type ShareResource, type ShareSecretResult, type SiteConfigUpdate, type SiteResource, type StatusCallback, type StorageMode, type TeamMemberResource, type TeamResource, type TmEntry, type TmSource, type TmSuggestion, type TranslationResource, type TypegenCollection, type TypegenField, type TypegenManifest, type TypegenRelation, type TypegenSchemaFilters, type UploadConfigResource, type UploadTypeCatalogueEntry, type UserPreferencesPayload, type UserResource, type VersionCompare, type VersionFieldChange, type ViewPreset, type WebSocketFactory, type WebSocketLike, type WebhookResource, checkCdcPipelineHealth, createAgentArtifact, createAgentGoal, createBookmark, createCdcPipeline, createLumiClient, decideAgentApproval, deleteBookmark, deleteCdcPipeline, deployCdc, dryRunAccessImport, evaluateAgentArtifact, exportAccessManifest, extractSeo, generateAgentApp, generateTypes, getEffectivePreset, graphql, importAccessManifest, jsonLdScript, legacyRest, listAgentApprovals, listAgentArtifacts, listAgentGoals, listAgentRuns, listAgentTools, listBookmarks, listCdcPipelines, mediaUrl, publishAgentArtifact, readAgentMemoryContext, readCdcPipeline, readCdcPipelineMetricHistory, readCdcPipelineMetrics, readItem, readItems, retryAgentRun, rollbackAgentArtifact, rollbackCdcDeployment, saveUserView, search, startCdcPipeline, stopCdcPipeline, toNextMetadata, updateBookmark, updateCdcPipeline, validateCdcDeploymentEnv, writeAgentMemory };

package/dist/index.d.ts

@@ -377,6 +377,12 @@ interface ListItemsParams {
     limit?: number;
     offset?: number;
     status?: string | null;
+    /**
+     * Controls whether the server computes the `count(*)` total. `'total_count'`
+     * (default) returns `meta.total`; `'none'` skips the extra aggregate query
+     * for a cheaper list (e.g. infinite scroll) and omits `meta.total`.
+     */
+    meta?: 'total_count' | 'none';
 }
 /** Reserved metadata attributes present on every search hit. */
 interface SearchHitMeta {
@@ -1365,8 +1371,29 @@ interface LumiClientOptions {
      * is thrown so a host (e.g. Studio) can clear the stale token and route
      * the operator back to the login screen. Errors thrown by the callback
      * are swallowed so they never mask the original `LumiError`.
+     *
+     * When auto-refresh is enabled (see `refreshToken`), `onUnauthorized`
+     * fires only AFTER a refresh attempt has also failed.
      */
     onUnauthorized?: () => void;
+    /**
+     * Rotating refresh token (body transport). When set, a `401` triggers a
+     * single `POST /api/v1/auth/refresh` with this token; on success the new
+     * access token is adopted and the original request is retried once. The
+     * refresh token rotates each call, so the new pair is surfaced via
+     * {@link onTokensRefreshed} for the host to persist. Omit to keep the
+     * legacy behaviour (no retry; `onUnauthorized` fires immediately).
+     */
+    refreshToken?: string;
+    /**
+     * Called after a successful silent refresh with the rotated token pair so
+     * the host can persist them (the old refresh token is now revoked).
+     */
+    onTokensRefreshed?: (tokens: {
+        token: string;
+        refreshToken: string;
+        refreshTokenExpiresAt?: string;
+    }) => void;
 }
 interface LumiResponse<T> {
     data: T;
@@ -1997,6 +2024,66 @@ declare function legacyRest(): <TSchema extends DefaultSchema>(client: LumiClien
     request: <T>(path: string, init?: RequestInit) => Promise<LumiResponse<T>>;
 };
 
+/**
+ * SDK commands for view presets (presets-inheritance) and media transform URLs
+ * (image-transform-dsl). Each is a command factory `(client) => Promise<T>`
+ * used with `client.request(...)`, matching the rest of the REST module.
+ *
+ * Content-version and translation-memory helpers live in the core SDK
+ * (`client.items(...).versions` and `client.tm`).
+ */
+
+type PresetScope = "user" | "role" | "global";
+interface ViewPreset {
+    id: string;
+    bookmark: string | null;
+    collection: string;
+    userId: string | null;
+    roleId: string | null;
+    layout: string;
+    layoutQuery: Record<string, unknown>;
+    layoutOptions: Record<string, unknown>;
+    search: string | null;
+    filter: Record<string, unknown>;
+    icon: string | null;
+    color: string | null;
+    refreshInterval: number;
+}
+interface ScopedViewPreset extends ViewPreset {
+    sourceScope: PresetScope;
+    roleDistance?: number;
+}
+declare function getEffectivePreset(collection: string): (client: LumiClient) => Promise<ScopedViewPreset | null>;
+declare function listBookmarks(collection: string): (client: LumiClient) => Promise<ScopedViewPreset[]>;
+/** Save (or overwrite) the acting user's default view for a collection. */
+declare function saveUserView(input: Partial<ViewPreset> & {
+    collection: string;
+}): (client: LumiClient) => Promise<ViewPreset>;
+declare function createBookmark(input: Partial<ViewPreset> & {
+    collection: string;
+    bookmark: string;
+}): (client: LumiClient) => Promise<ViewPreset>;
+declare function updateBookmark(id: string, input: Partial<ViewPreset>): (client: LumiClient) => Promise<ViewPreset>;
+declare function deleteBookmark(id: string): (client: LumiClient) => Promise<null>;
+interface MediaTransform {
+    width?: number;
+    height?: number;
+    format?: "webp" | "avif" | "jpeg" | "png";
+    quality?: number;
+    fit?: "cover" | "contain" | "fill" | "inside" | "outside";
+}
+/**
+ * Build a delivery URL for a media asset, optionally with a transform. Pass a
+ * `MediaTransform` for inline params, or `{ preset }` to reference a named
+ * server-side preset. Returns a path relative to the API base — the SDK client
+ * resolves it against its configured URL.
+ */
+declare function mediaUrl(key: string, transform?: MediaTransform | {
+    preset: string;
+}, opts?: {
+    sign?: string;
+}): (client: LumiClient) => string;
+
 /**
  * Full-text search via `GET /api/v1/search`. Omit `params.collection` for a
  * cross-collection (global) search that fans out over every collection of the
@@ -2129,4 +2216,4 @@ declare function toNextMetadata(item: unknown): Record<string, unknown>;
  */
 declare function jsonLdScript(item: unknown): string | undefined;
 
-export { ACCESS_EXPORT_SCHEMA, type AIApproval, type AIApprovalStatus, type AIChatResponse, type AIChatStatus, type AIContentAssistResult, type AIConversation, type AIFieldSuggestion, type AIMessage, type AccessConflict, type AccessConflictCheckInput, type AccessConflictReport, type AccessExportApiKey, type AccessExportBindings, type AccessExportManifest, type AccessExportPermission, type AccessExportPolicy, type AccessExportRole, type AccessImportApplyResult, type AccessImportDiff, type AccessImportDiffEntry, type AccessImportDiffSection, type AccessImportDryRunResult, type AccessImportIssue, type AccessImportMode, type AccessImportOptions, type AccessImportSummary, type ActivityResource, type AgentApprovalResource, type AgentArtifactCreateInput, type AgentArtifactResource, type AgentArtifactType, type AgentEvaluationResource, type AgentGenerateAppInput, type AgentGenerateAppResult, type AgentGoalCreateInput, type AgentGoalResource, type AgentMemoryContext, type AgentMemoryResource, type AgentMemoryWriteInput, type AgentRiskLevel, type AgentRunResource, type AgentToolResource, type ApiKeyCreateInput, type ApiKeyPolicyAttachment, type ApiKeyResource, type ApiKeyRoleAttachment, type ApiKeyRotateInput, type ApiKeySecretResult, AudienceClient, type AudienceClientOptions, type AudienceEvent, type AudienceNotification, type Brand, type CdcConnectorType, type CdcDeployInput, type CdcDeploymentResult, type CdcDeploymentStatus, type CdcDeploymentStep, type CdcDeploymentTarget, type CdcEnvValidationResult, type CdcHealthCheckResult, type CdcHealthMetricEntry, type CdcPipelineCreateInput, type CdcPipelineMetrics, type CdcPipelinePatchInput, type CdcPipelineResource, type CdcPipelineStatus, type CdcRollbackResult, type CdcValidateEnvInput, type ChannelEventCallback, type CollectionInput, type CollectionResource, type CompiledPermission, type ConnectionStatus, type ContentVersion, type CreateSCIMTokenParams, type DefaultSchema, type DeliverySeo, type DeploymentResource, type DeploymentTargetResource, type DomainCreateInput, type DomainResource, type DomainVerificationRecord, type ExtensionResource, type FieldDeleteOptions, type FieldInput, type FieldMutationOptions, type FieldRenameInput, type FieldResource, type FileResource, type FlowGraph, type FlowNode, type FlowResource, type FlowRun, type FlowRunResult, type FlowRunStatus, type FlowStatus, type FlowTriggerType, type FolderResource, type GenerateOptions, type GraphQLExtension, type ID, type ItemFilter, type ItemFilterOp, type ItemRow, type ListItemsParams, type ListItemsResponse, type ListMarketplaceExtensionsParams, type Locale, type LumiClient, type LumiClientOptions, LumiError, type LumiErrorBody, type LumiResponse, type MarketplaceExtension, type MarketplaceListResponse, type MaterializeDataResponse, type MaterializeProjection, type MaterializeRefreshResult, type MaterializeRefreshStrategy, type MaterializedCollection, type NotificationCallback, type PermissionAction, type PermissionBundle, type PermissionCheckResult, type PermissionRow, type PolicyDetail, type PolicyResource, type PresenceCallback, type PresenceEntry, type PresetResource, type PrimaryKeyType, RealtimeClient, type RealtimeEvent, type RealtimeEventCallback, type RelationInput, type RelationResource, type RelationType, type RevisionRow, type RoleDetail, type RoleResource, type SCIMTokenCreated, type SCIMTokenMeta, type SCIMTokenRotated, type SchemaApplyInput, type SchemaApplyResult, type SchemaChangedEvent, type SchemaDiff, type SchemaDiffEntry, type SchemaDiffInput, type SchemaDiffRisk, type SchemaRuntimeImpact, type SearchHit, type SearchHitMeta, type SearchParams, type SearchResponse, type SettingResource, type ShareCreateInput, type ShareResource, type ShareSecretResult, type SiteConfigUpdate, type SiteResource, type StatusCallback, type StorageMode, type TeamMemberResource, type TeamResource, type TmEntry, type TmSource, type TmSuggestion, type TranslationResource, type TypegenCollection, type TypegenField, type TypegenManifest, type TypegenRelation, type TypegenSchemaFilters, type UploadConfigResource, type UploadTypeCatalogueEntry, type UserPreferencesPayload, type UserResource, type VersionCompare, type VersionFieldChange, type WebSocketFactory, type WebSocketLike, type WebhookResource, checkCdcPipelineHealth, createAgentArtifact, createAgentGoal, createCdcPipeline, createLumiClient, decideAgentApproval, deleteCdcPipeline, deployCdc, dryRunAccessImport, evaluateAgentArtifact, exportAccessManifest, extractSeo, generateAgentApp, generateTypes, graphql, importAccessManifest, jsonLdScript, legacyRest, listAgentApprovals, listAgentArtifacts, listAgentGoals, listAgentRuns, listAgentTools, listCdcPipelines, publishAgentArtifact, readAgentMemoryContext, readCdcPipeline, readCdcPipelineMetricHistory, readCdcPipelineMetrics, readItem, readItems, retryAgentRun, rollbackAgentArtifact, rollbackCdcDeployment, search, startCdcPipeline, stopCdcPipeline, toNextMetadata, updateCdcPipeline, validateCdcDeploymentEnv, writeAgentMemory };
+export { ACCESS_EXPORT_SCHEMA, type AIApproval, type AIApprovalStatus, type AIChatResponse, type AIChatStatus, type AIContentAssistResult, type AIConversation, type AIFieldSuggestion, type AIMessage, type AccessConflict, type AccessConflictCheckInput, type AccessConflictReport, type AccessExportApiKey, type AccessExportBindings, type AccessExportManifest, type AccessExportPermission, type AccessExportPolicy, type AccessExportRole, type AccessImportApplyResult, type AccessImportDiff, type AccessImportDiffEntry, type AccessImportDiffSection, type AccessImportDryRunResult, type AccessImportIssue, type AccessImportMode, type AccessImportOptions, type AccessImportSummary, type ActivityResource, type AgentApprovalResource, type AgentArtifactCreateInput, type AgentArtifactResource, type AgentArtifactType, type AgentEvaluationResource, type AgentGenerateAppInput, type AgentGenerateAppResult, type AgentGoalCreateInput, type AgentGoalResource, type AgentMemoryContext, type AgentMemoryResource, type AgentMemoryWriteInput, type AgentRiskLevel, type AgentRunResource, type AgentToolResource, type ApiKeyCreateInput, type ApiKeyPolicyAttachment, type ApiKeyResource, type ApiKeyRoleAttachment, type ApiKeyRotateInput, type ApiKeySecretResult, AudienceClient, type AudienceClientOptions, type AudienceEvent, type AudienceNotification, type Brand, type CdcConnectorType, type CdcDeployInput, type CdcDeploymentResult, type CdcDeploymentStatus, type CdcDeploymentStep, type CdcDeploymentTarget, type CdcEnvValidationResult, type CdcHealthCheckResult, type CdcHealthMetricEntry, type CdcPipelineCreateInput, type CdcPipelineMetrics, type CdcPipelinePatchInput, type CdcPipelineResource, type CdcPipelineStatus, type CdcRollbackResult, type CdcValidateEnvInput, type ChannelEventCallback, type CollectionInput, type CollectionResource, type CompiledPermission, type ConnectionStatus, type ContentVersion, type CreateSCIMTokenParams, type DefaultSchema, type DeliverySeo, type DeploymentResource, type DeploymentTargetResource, type DomainCreateInput, type DomainResource, type DomainVerificationRecord, type ExtensionResource, type FieldDeleteOptions, type FieldInput, type FieldMutationOptions, type FieldRenameInput, type FieldResource, type FileResource, type FlowGraph, type FlowNode, type FlowResource, type FlowRun, type FlowRunResult, type FlowRunStatus, type FlowStatus, type FlowTriggerType, type FolderResource, type GenerateOptions, type GraphQLExtension, type ID, type ItemFilter, type ItemFilterOp, type ItemRow, type ListItemsParams, type ListItemsResponse, type ListMarketplaceExtensionsParams, type Locale, type LumiClient, type LumiClientOptions, LumiError, type LumiErrorBody, type LumiResponse, type MarketplaceExtension, type MarketplaceListResponse, type MaterializeDataResponse, type MaterializeProjection, type MaterializeRefreshResult, type MaterializeRefreshStrategy, type MaterializedCollection, type MediaTransform, type NotificationCallback, type PermissionAction, type PermissionBundle, type PermissionCheckResult, type PermissionRow, type PolicyDetail, type PolicyResource, type PresenceCallback, type PresenceEntry, type PresetResource, type PresetScope, type PrimaryKeyType, RealtimeClient, type RealtimeEvent, type RealtimeEventCallback, type RelationInput, type RelationResource, type RelationType, type RevisionRow, type RoleDetail, type RoleResource, type SCIMTokenCreated, type SCIMTokenMeta, type SCIMTokenRotated, type SchemaApplyInput, type SchemaApplyResult, type SchemaChangedEvent, type SchemaDiff, type SchemaDiffEntry, type SchemaDiffInput, type SchemaDiffRisk, type SchemaRuntimeImpact, type ScopedViewPreset, type SearchHit, type SearchHitMeta, type SearchParams, type SearchResponse, type SettingResource, type ShareCreateInput, type ShareResource, type ShareSecretResult, type SiteConfigUpdate, type SiteResource, type StatusCallback, type StorageMode, type TeamMemberResource, type TeamResource, type TmEntry, type TmSource, type TmSuggestion, type TranslationResource, type TypegenCollection, type TypegenField, type TypegenManifest, type TypegenRelation, type TypegenSchemaFilters, type UploadConfigResource, type UploadTypeCatalogueEntry, type UserPreferencesPayload, type UserResource, type VersionCompare, type VersionFieldChange, type ViewPreset, type WebSocketFactory, type WebSocketLike, type WebhookResource, checkCdcPipelineHealth, createAgentArtifact, createAgentGoal, createBookmark, createCdcPipeline, createLumiClient, decideAgentApproval, deleteBookmark, deleteCdcPipeline, deployCdc, dryRunAccessImport, evaluateAgentArtifact, exportAccessManifest, extractSeo, generateAgentApp, generateTypes, getEffectivePreset, graphql, importAccessManifest, jsonLdScript, legacyRest, listAgentApprovals, listAgentArtifacts, listAgentGoals, listAgentRuns, listAgentTools, listBookmarks, listCdcPipelines, mediaUrl, publishAgentArtifact, readAgentMemoryContext, readCdcPipeline, readCdcPipelineMetricHistory, readCdcPipelineMetrics, readItem, readItems, retryAgentRun, rollbackAgentArtifact, rollbackCdcDeployment, saveUserView, search, startCdcPipeline, stopCdcPipeline, toNextMetadata, updateBookmark, updateCdcPipeline, validateCdcDeploymentEnv, writeAgentMemory };

package/dist/index.js

@@ -34,12 +34,52 @@ function toErrorBody(status, body) {
 function createLumiClient(opts) {
   const fetcher = opts.fetcher ?? globalThis.fetch;
   const base = opts.url.replace(/\/$/, "");
-  async function rawRequest(path, init = {}) {
+  let currentToken = opts.token;
+  let currentRefreshToken = opts.refreshToken;
+  let refreshInFlight = null;
+  async function attemptRefresh() {
+    if (!currentRefreshToken) return false;
+    if (!refreshInFlight) {
+      refreshInFlight = (async () => {
+        try {
+          const res = await fetcher(`${base}/api/v1/auth/refresh`, {
+            method: "POST",
+            headers: {
+              "content-type": "application/json",
+              "x-lumi-site": opts.siteId
+            },
+            // Body transport is CSRF-exempt (the token isn't ambient).
+            body: JSON.stringify({ refreshToken: currentRefreshToken })
+          });
+          if (!res.ok) return false;
+          const data = parseResponseBody(await res.text())?.data;
+          if (!data?.token || !data.refreshToken) return false;
+          currentToken = data.token;
+          currentRefreshToken = data.refreshToken;
+          try {
+            opts.onTokensRefreshed?.({
+              token: data.token,
+              refreshToken: data.refreshToken,
+              refreshTokenExpiresAt: data.refreshTokenExpiresAt
+            });
+          } catch {
+          }
+          return true;
+        } catch {
+          return false;
+        } finally {
+          refreshInFlight = null;
+        }
+      })();
+    }
+    return refreshInFlight;
+  }
+  async function rawRequest(path, init = {}, retried = false) {
     const headers = new Headers(init.headers);
     for (const [key, value] of Object.entries(opts.headers ?? {})) {
       headers.set(key, value);
     }
-    headers.set("authorization", `Bearer ${opts.token}`);
+    headers.set("authorization", `Bearer ${currentToken}`);
     headers.set("x-lumi-site", opts.siteId);
     if (!headers.has("content-type") && init.body) {
       headers.set("content-type", "application/json");
@@ -48,6 +88,11 @@ function createLumiClient(opts) {
     const text = await res.text();
     const body = parseResponseBody(text);
     if (!res.ok) {
+      if (res.status === 401 && !retried && currentRefreshToken && path !== "/api/v1/auth/refresh") {
+        if (await attemptRefresh()) {
+          return rawRequest(path, init, true);
+        }
+      }
       if (res.status === 401 && opts.onUnauthorized) {
         try {
           opts.onUnauthorized();
@@ -60,7 +105,9 @@ function createLumiClient(opts) {
   }
   const baseClient = {
     url: opts.url,
-    token: opts.token,
+    get token() {
+      return currentToken;
+    },
     siteId: opts.siteId,
     fetcher,
     rawRequest,
@@ -1048,6 +1095,79 @@ function legacyRest() {
   };
 }
 
+// src/rest/gaps.ts
+function getEffectivePreset(collection) {
+  return async (client) => {
+    const res = await client.rawRequest(
+      `/api/v1/presets/effective?collection=${encodeURIComponent(collection)}`
+    );
+    return res.data;
+  };
+}
+function listBookmarks(collection) {
+  return async (client) => {
+    const res = await client.rawRequest(
+      `/api/v1/presets/bookmarks?collection=${encodeURIComponent(collection)}`
+    );
+    return res.data;
+  };
+}
+function saveUserView(input) {
+  return async (client) => {
+    const res = await client.rawRequest("/api/v1/presets", {
+      method: "POST",
+      body: JSON.stringify({ ...input, bookmark: null })
+    });
+    return res.data;
+  };
+}
+function createBookmark(input) {
+  return async (client) => {
+    const res = await client.rawRequest("/api/v1/presets", {
+      method: "POST",
+      body: JSON.stringify(input)
+    });
+    return res.data;
+  };
+}
+function updateBookmark(id, input) {
+  return async (client) => {
+    const res = await client.rawRequest(`/api/v1/presets/${encodeURIComponent(id)}`, {
+      method: "PATCH",
+      body: JSON.stringify(input)
+    });
+    return res.data;
+  };
+}
+function deleteBookmark(id) {
+  return async (client) => {
+    const res = await client.rawRequest(`/api/v1/presets/${encodeURIComponent(id)}`, {
+      method: "DELETE"
+    });
+    return res.data;
+  };
+}
+function mediaUrl(key, transform, opts) {
+  return (client) => {
+    const base = client.url.replace(/\/$/, "");
+    const path = `/api/v1/media/${key.split("/").map(encodeURIComponent).join("/")}`;
+    if (!transform) return `${base}${path}`;
+    const qs = new URLSearchParams();
+    if ("preset" in transform) {
+      qs.set("preset", transform.preset);
+    } else {
+      if (transform.width !== void 0) qs.set("width", String(transform.width));
+      if (transform.height !== void 0) qs.set("height", String(transform.height));
+      if (transform.format) qs.set("format", transform.format);
+      if (transform.quality !== void 0) qs.set("quality", String(transform.quality));
+      if (transform.fit) qs.set("fit", transform.fit);
+      if (opts?.sign) qs.set("sig", opts.sign);
+    }
+    const query = qs.toString();
+    return query ? `${base}${path}?${query}` : `${base}${path}`;
+  };
+}
+
 // src/rest/index.ts
 function search(query, params) {
   return async (client) => {
@@ -1071,6 +1191,7 @@ function readItems(collection, params) {
     if (params?.limit !== void 0) qs.set("limit", String(params.limit));
     if (params?.offset !== void 0) qs.set("offset", String(params.offset));
     if (params?.status) qs.set("status", params.status);
+    if (params?.meta) qs.set("meta", params.meta);
     const s = qs.toString();
     const query = s ? `?${s}` : "";
     const res = await client.rawRequest(`/api/v1/items/${collection}${query}`);
@@ -1521,9 +1642,11 @@ export {
   checkCdcPipelineHealth,
   createAgentArtifact,
   createAgentGoal,
+  createBookmark,
   createCdcPipeline,
   createLumiClient,
   decideAgentApproval,
+  deleteBookmark,
   deleteCdcPipeline,
   deployCdc,
   dryRunAccessImport,
@@ -1532,6 +1655,7 @@ export {
   extractSeo,
   generateAgentApp,
   generateTypes,
+  getEffectivePreset,
   graphql,
   importAccessManifest,
   jsonLdScript,
@@ -1541,7 +1665,9 @@ export {
   listAgentGoals,
   listAgentRuns,
   listAgentTools,
+  listBookmarks,
   listCdcPipelines,
+  mediaUrl,
   publishAgentArtifact,
   readAgentMemoryContext,
   readCdcPipeline,
@@ -1552,10 +1678,12 @@ export {
   retryAgentRun,
   rollbackAgentArtifact,
   rollbackCdcDeployment,
+  saveUserView,
   search,
   startCdcPipeline,
   stopCdcPipeline,
   toNextMetadata,
+  updateBookmark,
   updateCdcPipeline,
   validateCdcDeploymentEnv,
   writeAgentMemory

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumibase/sdk",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "description": "LumiBase JS SDK (REST + WebSocket) + typegen core. Isomorphic ESM.",
   "type": "module",
   "repository": {