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

package/dist/index.d.ts

@@ -21,6 +21,14 @@ declare interface ApiClient {
      * 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.
      *
@@ -85,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;
@@ -445,6 +464,13 @@ declare interface Options {
      * 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 = {
@@ -491,6 +517,14 @@ 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. */
@@ -499,6 +533,16 @@ declare interface SnapshotMeta {
     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;
@@ -519,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@content-island/vscode-api-client",
-  "version": "0.2.4",
+  "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.23.0"
+    "@content-island/api-client": "0.24.0"
   },
   "devDependencies": {
     "@content-island/common-backend": "*",