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

package/dist/index.d.ts

@@ -5,12 +5,22 @@ 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>;
     /**
      * Updates (or upserts, when selected by `fieldName`+`language`) a field value on an existing content.
      *
@@ -58,6 +68,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;
@@ -420,6 +432,19 @@ 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;
 }
 
 declare type Pagination = {
@@ -437,6 +462,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 +491,14 @@ declare interface SaveModelResponse {
     id: string;
 }
 
+declare interface SnapshotMeta {
+    schemaVersion: number;
+    /** ISO-8601 timestamp of when the snapshot was generated on the server. */
+    exportedAt: string;
+    projectId: string;
+    view: 'published' | 'preview';
+}
+
 declare type SortableFields<M extends Model> = {
     contentType?: SortOrder;
     lastUpdate?: SortOrder;

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.4",
   "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.23.0"
   },
   "devDependencies": {
     "@content-island/common-backend": "*",