@content-island/vscode-api-client 0.2.3 → 0.2.5

package/dist/index.d.ts

@@ -5,12 +5,30 @@ declare type AllowedFields<M extends Model, Type extends 'sort' | 'filter'> = Pa
 }, 'fields.id' | 'fields.language'>>;
 
 declare interface ApiClient {
+    /**
+     * Resolves the project. Routed by the client-level mode only (no per-query override): served from
+     * the snapshot's `project` block in `'snapshot'` mode, from the API in `'api'` mode.
+     */
     getProject: () => Promise<Project>;
     getContentList: <M extends Model = Model & Record<string, any>>(queryParam?: ContentListQueryParams<M>) => Promise<M[]>;
     getContent: <M extends Model = Model & Record<string, any>>(queryParam: ContentQueryParams<M>) => Promise<M>;
     getRawContentList: <M extends Model = Model & Record<string, any>>(queryParam?: ContentListQueryParams<M>) => Promise<Content[]>;
     getRawContent: <M extends Model = Model & Record<string, any>>(queryParam: ContentQueryParams<M>) => Promise<Content>;
     getContentListSize: <M extends Model = Model & Record<string, any>>(queryParam?: ContentListSizeQueryParams<M>) => Promise<number>;
+    /**
+     * Resolves the snapshot's `meta` block, lazily loading the snapshot regardless of mode (from
+     * `snapshotPath`, or `DEFAULT_SNAPSHOT_PATH` when omitted). Rejects with an `ApiClientError` from
+     * the loader on a missing/unreadable/invalid file.
+     */
+    getSnapshotInfo: () => Promise<SnapshotMeta>;
+    /**
+     * Pulls a fresh snapshot via the configured `snapshotLoader`, validates and guards it, and atomically
+     * swaps the active snapshot when the incoming one is newer. Returns `{ status: 'updated', meta }` on
+     * adoption or `{ status: 'unchanged', meta }` when the anti-regression guard retains the current one.
+     * Throws `ApiClientError` in `'api'` mode, without a configured `snapshotLoader`, or on a
+     * loader/validation/identity failure (the active snapshot is left untouched).
+     */
+    refreshSnapshot: () => Promise<SnapshotRefreshResult>;
     /**
      * Updates (or upserts, when selected by `fieldName`+`language`) a field value on an existing content.
      *
@@ -58,6 +76,8 @@ export declare type ClientFilter<Type = string | boolean | number> = Type | {
     nin?: Type[];
 };
 
+declare type ClientMode = 'api' | 'snapshot';
+
 export declare interface Content {
     id: string;
     name: string;
@@ -73,6 +93,17 @@ export declare type ContentListSizeQueryParams<M extends Model = Model & Record<
 
 export declare type ContentQueryParams<M extends Model = Model & Record<string, any>> = Omit<QueryParams<M>, 'sort' | 'pagination'>;
 
+/**
+ * The full content snapshot document produced by `GET /project/export` and consumed
+ * by the api-client in static mode. `contents` is serialized in the existing API
+ * `Content` shape at related-content depth 0.
+ */
+declare interface ContentSnapshot {
+    meta: SnapshotMeta;
+    project: Project;
+    contents: Content[];
+}
+
 declare interface ContentTypeField extends Lookup {
     type: FieldType;
     tsType: string;
@@ -420,6 +451,26 @@ declare interface Options {
     secureProtocol?: boolean;
     apiVersion?: string;
     metadata?: string;
+    /**
+     * Client-level mode. `'api'` (default) performs network requests against the B2B API;
+     * `'snapshot'` serves reads from a snapshot file loaded from `snapshotPath`.
+     */
+    mode?: ClientMode;
+    /**
+     * Path to a content snapshot file (produced by `content-island export`). Optional and cwd-relative;
+     * defaults to `DEFAULT_SNAPSHOT_PATH` — the same path the CLI writes by default, so export followed
+     * by `createClient({ mode: 'snapshot' })` resolves the same file with zero config. Independent of
+     * `mode`: an `'api'` client may still set it to expose `getSnapshotInfo()`. A missing/unreadable/
+     * invalid file at the resolved path rejects with an `ApiClientError` from the loader.
+     */
+    snapshotPath?: string;
+    /**
+     * Optional loader for a refreshable snapshot in `'snapshot'` mode. When set without `snapshotPath`
+     * (loader-only), the client resolves the active snapshot via the loader on first read. Required for
+     * `refreshSnapshot()`; calling `refreshSnapshot()` without it throws an `ApiClientError`. A
+     * `snapshotPath`-only client (no loader) keeps the static 0.1.0 behavior.
+     */
+    snapshotLoader?: SnapshotLoader;
 }
 
 declare type Pagination = {
@@ -437,6 +488,26 @@ export declare interface Project {
 declare type QueryParams<M extends Model = Model & Record<string, any>> = FilterableFields<M> & {
     sort?: SortableFields<M>;
     pagination?: Pagination;
+    /**
+     * Per-query mode override (effective mode = per-query `mode` ?? client-level `mode` ?? `'api'`).
+     * Client-only key — never serialized into the query string.
+     */
+    mode?: ClientMode;
+    /**
+     * Called exactly once with the related-content resolution metadata; when omitted, behavior and
+     * return shapes are unchanged. Client-only key — never serialized into the query string.
+     */
+    onRelatedContentMeta?: (meta: RelatedContentMeta) => void;
+};
+
+/**
+ * Related-content resolution metadata for a read: how deep the BFS resolved (`resolvedDepth`) and
+ * whether a depth/budget cap left the graph `partial`. Identical values in both modes for the same
+ * data and query (header-sourced in api mode, engine-sourced in snapshot mode).
+ */
+declare type RelatedContentMeta = {
+    resolvedDepth: number;
+    partial: boolean;
 };
 
 declare type RelatedModelType = `${string}|${string}`;
@@ -446,6 +517,32 @@ declare interface SaveModelResponse {
     id: string;
 }
 
+/**
+ * User-provided fetch for a refreshable snapshot. Opaque to the core: it may read a blob/S3/file or
+ * call `exportSnapshot()`. Returns either raw snapshot JSON text (which the client `JSON.parse`s) or
+ * an already-parsed `ContentSnapshot` object (passed through as-is). Invoked only on the first read in
+ * the loader-only case and on `refreshSnapshot()` — never during `createClient` construction.
+ */
+declare type SnapshotLoader = () => Promise<string | ContentSnapshot>;
+
+declare interface SnapshotMeta {
+    schemaVersion: number;
+    /** ISO-8601 timestamp of when the snapshot was generated on the server. */
+    exportedAt: string;
+    projectId: string;
+    view: 'published' | 'preview';
+}
+
+/**
+ * Outcome of a `refreshSnapshot()` call. `'updated'` when the incoming snapshot was adopted as the new
+ * active snapshot (its `meta` is returned); `'unchanged'` when the anti-regression guard kept the
+ * current active snapshot (the retained snapshot's `meta` is returned).
+ */
+declare type SnapshotRefreshResult = {
+    status: 'updated' | 'unchanged';
+    meta: SnapshotMeta;
+};
+
 declare type SortableFields<M extends Model> = {
     contentType?: SortOrder;
     lastUpdate?: SortOrder;
@@ -466,7 +563,7 @@ declare interface UploadMediaParams {
 
 declare type Validation = { name: string; customArgs?: any };
 
-export declare interface VSCodeApiClient extends Omit<ApiClient, 'createModel' | 'updateModel' | 'deleteModel' | 'createEnum' | 'updateEnum' | 'deleteEnum'> {
+export declare interface VSCodeApiClient extends Omit<ApiClient, 'createModel' | 'updateModel' | 'deleteModel' | 'createEnum' | 'updateEnum' | 'deleteEnum' | 'refreshSnapshot'> {
     setVSCodeExtensionContext: (context: vscode.ExtensionContext) => void;
     authorize: (authorizationCode: string, metadata: string) => Promise<void>;
     authorizeByProjectId: (projectId: string) => Promise<void>;

package/dist/index.js

@@ -2,52 +2,52 @@ import { isApiClientError as I, createClient as A } from "@content-island/api-cl
 import { mapContentToModel as z } from "@content-island/api-client";
 import * as c from "vscode";
 import _ from "node:crypto";
-import P from "node:util";
-let g;
-const S = () => {
-  if (!g)
+import S from "node:util";
+let C;
+const P = () => {
+  if (!C)
     throw new Error("Extension context has not been set.");
-  return g;
-}, L = (t) => {
-  g = t;
+  return C;
+}, f = (t) => {
+  C = t;
 };
 let l = {
-  getContext: S,
-  setContext: L
+  getContext: P,
+  setContext: f
 };
 const d = {
   IS_PRODUCTION: !0,
   DEFAULT_API_CLIENT_DOMAIN: "api.contentisland.net",
   DEFAULT_API_CLIENT_VERSION: "1.0",
   DEFAULT_LOGIN_DOMAIN: "app.contentisland.net"
-}, C = "content-island-vscode", u = {
-  SALT: `${C}.salt`,
-  ACCESS_TOKEN_BY_PROJECT_ID: (t) => `${C}.access-token.${t}`,
-  METADATA_BY_PROJECT_ID: (t) => `${C}.metadata.${t}`
-}, E = {
+}, w = "content-island-vscode", u = {
+  SALT: `${w}.salt`,
+  ACCESS_TOKEN_BY_PROJECT_ID: (t) => `${w}.access-token.${t}`,
+  METADATA_BY_PROJECT_ID: (t) => `${w}.metadata.${t}`
+}, h = {
   get: async (t) => await l.getContext().secrets.get(u.METADATA_BY_PROJECT_ID(t)),
   set: async (t, o) => {
     await l.getContext().secrets.store(u.METADATA_BY_PROJECT_ID(t), o);
   }
-}, h = {
+}, E = {
   get: async (t) => await l.getContext().secrets.get(u.ACCESS_TOKEN_BY_PROJECT_ID(t)),
   set: async (t, o) => {
     await l.getContext().secrets.store(u.ACCESS_TOKEN_BY_PROJECT_ID(t), o);
   }
-}, f = (t) => {
-  const s = (t.secureProtocol === void 0 ? d.IS_PRODUCTION : t.secureProtocol) ? "https" : "http", e = t.domain ? t.domain : d.DEFAULT_API_CLIENT_DOMAIN, n = t.apiVersion ? t.apiVersion : d.DEFAULT_API_CLIENT_VERSION;
-  return `${s}://${e}/api/${n}`;
+}, L = (t) => {
+  const a = (t.secureProtocol === void 0 ? d.IS_PRODUCTION : t.secureProtocol) ? "https" : "http", e = t.domain ? t.domain : d.DEFAULT_API_CLIENT_DOMAIN, n = t.apiVersion ? t.apiVersion : d.DEFAULT_API_CLIENT_VERSION;
+  return `${a}://${e}/api/${n}`;
 }, p = (t) => {
-  const s = (t.secureProtocol === void 0 ? d.IS_PRODUCTION : t.secureProtocol) ? "https" : "http", e = t.loginDomain ? t.loginDomain : d.DEFAULT_LOGIN_DOMAIN;
-  return `${s}://${e}/#/?redirect=vscode`;
-}, y = 16, O = (t = y) => _.randomBytes(t).toString("hex"), x = 64, D = "sha512", m = 1e5, N = async (t, o, s = x) => (await P.promisify(_.pbkdf2)(t, o, m, s, D)).toString("hex"), k = async () => {
+  const a = (t.secureProtocol === void 0 ? d.IS_PRODUCTION : t.secureProtocol) ? "https" : "http", e = t.loginDomain ? t.loginDomain : d.DEFAULT_LOGIN_DOMAIN;
+  return `${a}://${e}/#/?redirect=vscode`;
+}, y = 16, O = (t = y) => _.randomBytes(t).toString("hex"), x = 64, D = "sha512", m = 1e5, N = async (t, o, a = x) => (await S.promisify(_.pbkdf2)(t, o, m, a, D)).toString("hex"), k = async () => {
   const t = l.getContext();
   let o = await t.secrets.get(u.SALT);
   return o || (o = O(32), await t.secrets.store(u.SALT, o)), o;
 }, M = 32, R = async (t) => {
   const o = await k();
   return await N(t, o, M);
-}, w = async (t) => {
+}, g = async (t) => {
   const o = "Open Login Page";
   if (await c.window.showInformationMessage(
     "You need to log in to Content Island to continue. Do you want to open the login page?",
@@ -56,23 +56,23 @@ const d = {
     return;
   const e = c.Uri.parse(p(t));
   await c.env.openExternal(e);
-}, r = (t, o) => async (...s) => {
+}, s = (t, o) => async (...a) => {
   try {
-    return await t(...s);
+    return await t(...a);
   } catch (e) {
     if (I(e)) {
       if (e.status === 401)
-        throw await w(o), new Error("Unauthorized: Please log in to continue.");
+        throw await g(o), new Error("Unauthorized: Please log in to continue.");
       e.status === 403 && c.window.showErrorMessage("Access forbidden: You do not have permission to perform this action.");
     }
     throw e;
   }
-}, U = async (t, o, s) => {
-  const e = f(t);
+}, U = async (t, o, a) => {
+  const e = L(t);
   let n;
-  const a = {
+  const r = {
     authorizationCode: o,
-    metadata: s
+    metadata: a
   };
   try {
     n = await fetch(`${e}/security/vscode/token`, {
@@ -80,7 +80,7 @@ const d = {
       headers: {
         "Content-Type": "application/json"
       },
-      body: JSON.stringify(a)
+      body: JSON.stringify(r)
     });
   } catch {
     c.window.showErrorMessage(
@@ -89,7 +89,7 @@ const d = {
     return;
   }
   if (!n.ok) {
-    n.status === 401 ? await w(t) : n.status === 403 && c.window.showErrorMessage(
+    n.status === 401 ? await g(t) : n.status === 403 && c.window.showErrorMessage(
       "You do not have permission to access this resource. Please check your access rights in Content Island."
     ), c.window.showErrorMessage(
       "Failed to obtain access token. Please complete the authorization in Content Island."
@@ -98,16 +98,16 @@ const d = {
   }
   try {
     const i = await n.json();
-    return (!i?.accessToken || typeof i.accessToken != "string") && (c.window.showErrorMessage("Invalid response from the authorization server."), await w(t)), i.accessToken;
+    return (!i?.accessToken || typeof i.accessToken != "string") && (c.window.showErrorMessage("Invalid response from the authorization server."), await g(t)), i.accessToken;
   } catch {
     c.window.showErrorMessage("Error processing response from the authorization server.");
   }
 }, T = (t) => {
-  const o = `PREVIEW_${t.accessToken}`, s = A({ ...t, accessToken: o });
+  const o = `PREVIEW_${t.accessToken}`, a = A({ ...t, accessToken: o });
   return {
-    ...s,
+    ...a,
     getProject: async () => {
-      const e = await s.getProject();
+      const e = await a.getProject();
       return {
         ...e,
         id: await R(e.id)
@@ -116,42 +116,43 @@ const d = {
   };
 }, B = (t = {}) => {
   let o = T({ ...t, accessToken: "" });
-  const s = (e, n) => {
+  const a = (e, n) => {
     o = T({ ...t, accessToken: e, metadata: n });
   };
   return {
     authorize: async (e, n) => {
-      const a = await U(t, e, n);
-      if (a) {
-        s(a, n);
+      const r = await U(t, e, n);
+      if (r) {
+        a(r, n);
         const i = await o.getProject();
-        await h.set(i.id, a), await E.set(i.id, n);
+        await E.set(i.id, r), await h.set(i.id, n);
       }
     },
     authorizeByProjectId: async (e) => {
-      const n = await h.get(e), a = await E.get(e);
-      if (!n || !a) {
-        await w(t);
+      const n = await E.get(e), r = await h.get(e);
+      if (!n || !r) {
+        await g(t);
         return;
       }
-      s(n, a);
+      a(n, r);
     },
     setVSCodeExtensionContext: (e) => {
       l.setContext(e);
     },
-    getProject: (...e) => r(() => o.getProject(...e), t)(),
-    getContentList: (...e) => r(() => o.getContentList(...e), t)(),
-    getContent: (...e) => r(() => o.getContent(...e), t)(),
-    getRawContentList: (...e) => r(() => o.getRawContentList(...e), t)(),
-    getRawContent: (...e) => r(() => o.getRawContent(...e), t)(),
-    getContentListSize: (...e) => r(() => o.getContentListSize(...e), t)(),
-    updateContentFieldValue: (e, n, a) => r(
-      () => o.updateContentFieldValue(e, n, a),
+    getProject: (...e) => s(() => o.getProject(...e), t)(),
+    getContentList: (...e) => s(() => o.getContentList(...e), t)(),
+    getContent: (...e) => s(() => o.getContent(...e), t)(),
+    getRawContentList: (...e) => s(() => o.getRawContentList(...e), t)(),
+    getRawContent: (...e) => s(() => o.getRawContent(...e), t)(),
+    getContentListSize: (...e) => s(() => o.getContentListSize(...e), t)(),
+    getSnapshotInfo: (...e) => s(() => o.getSnapshotInfo(...e), t)(),
+    updateContentFieldValue: (e, n, r) => s(
+      () => o.updateContentFieldValue(e, n, r),
       t
     )(),
-    uploadMedia: (...e) => r(() => o.uploadMedia(...e), t)(),
-    createContent: (...e) => r(() => o.createContent(...e), t)(),
-    publishContent: (...e) => r(() => o.publishContent(...e), t)()
+    uploadMedia: (...e) => s(() => o.uploadMedia(...e), t)(),
+    createContent: (...e) => s(() => o.createContent(...e), t)(),
+    publishContent: (...e) => s(() => o.publishContent(...e), t)()
   };
 };
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@content-island/vscode-api-client",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "Content Island - VSCode Extension API Client",
   "private": false,
   "sideEffects": false,
@@ -32,7 +32,7 @@
     "test:watch": "vitest -c ./config/test/config.ts"
   },
   "dependencies": {
-    "@content-island/api-client": "0.22.0"
+    "@content-island/api-client": "0.24.0"
   },
   "devDependencies": {
     "@content-island/common-backend": "*",