skapi-js 1.8.1 → 1.8.3

package/dist/skapi.d.mts

@@ -51,7 +51,7 @@ type GetRecordQuery = {
     record_id?: string;
     /** Table name not required when "record_id" is given. A bare string is shorthand for { name: <string> }. */
     table?: string | {
-        /** Max 128 chars. Blocks: / ! * #, control chars, and sentinel 􏿿. */
+        /** Max 256 characters, where / ! * # % each count as 3. Blocks control chars and sentinel 􏿿. */
         name: string;
         /** Number range: 0 ~ 99. Default: 'public' */
         access_group?: number | 'private' | 'public' | 'authorized' | 'admin';
@@ -65,9 +65,9 @@ type GetRecordQuery = {
     };
     /** Index condition and range cannot be used simultaneously.*/
     index?: {
-        /** Custom names: max 128 chars, cannot start with "$", blocks / ! * #, control chars, and sentinel 􏿿. Reserved names: $uploaded, $updated, $referenced_count, $user_id. */
+        /** Custom names: max 256 characters, where / ! * # % each count as 3. Cannot start with "$". Blocks control chars and sentinel 􏿿. Reserved names: $uploaded, $updated, $referenced_count, $user_id. */
         name: string | '$updated' | '$uploaded' | '$referenced_count' | '$user_id';
-        /** String value max 256 chars. Allows punctuation (including / ! * #). Blocks control chars and sentinel 􏿿. */
+        /** String value max 256 characters. Any punctuation is allowed and counts as one character, and values compare exactly as written. Blocks control chars and sentinel 􏿿. */
         value: string | number | boolean;
         /** For a string value: '>=' = 'starts with', '<=' = 'ends with'. When the name is a compound name ending in '.', '>=' / '<=' match the child name segment (starts / ends with). '>' / '<' are lexicographic; numbers/booleans compare normally. */
         condition?: Condition;
@@ -81,7 +81,7 @@ type PostRecordConfig = {
     readonly?: boolean;
     /** Table name not required when "record_id" is given.*/
     table?: {
-        /** Max 128 chars. Blocks: / ! * #, control chars, and sentinel 􏿿. */
+        /** Max 256 characters, where / ! * # % each count as 3. Blocks control chars and sentinel 􏿿. */
         name?: string;
         /** Number range: 0 ~ 99. Default: 'public' */
         access_group?: number | 'private' | 'public' | 'authorized' | 'admin';
@@ -114,9 +114,9 @@ type PostRecordConfig = {
     reference?: string | null;
     /** null removes index */
     index?: {
-        /** Max 128 chars, cannot start with "$", blocks / ! * #, control chars, and sentinel 􏿿. */
+        /** Max 256 characters, where / ! * # % each count as 3. Cannot start with "$". Blocks control chars and sentinel 􏿿. */
         name: string;
-        /** String value max 256 chars. Allows punctuation (including / ! * #). Blocks control chars and sentinel 􏿿. */
+        /** String value max 256 characters. Any punctuation is allowed and counts as one character, and values compare exactly as written. Blocks control chars and sentinel 􏿿. */
         value: string | number | boolean;
     } | null;
     tags?: string[] | null;
@@ -176,6 +176,17 @@ type RecordData = {
     };
     ip: string;
     readonly: boolean;
+    /**
+     * Present ONLY on an element of a postRecords() result that the backend refused.
+     * Such an element is an empty record (record_id is ""), and this carries the reason
+     * the backend gave, e.g. { code: 'NOT_EXISTS', message: 'Reference "..." does not exists.' }.
+     * A saved record never has it, so `record_id` stays the test for "did this save".
+     */
+    error?: {
+        code?: string;
+        message?: string;
+        [key: string]: any;
+    };
 };
 type Connection = {
     /** User's locale */
@@ -653,6 +664,17 @@ declare class Skapi {
     owner: string;
     session: Record<string, any> | null;
     connection: Connection | null;
+    /**
+     * unique_id -> record_id, bucketed by a "<service>/<owner>" scope key.
+     *
+     * The scope is mandatory. One Skapi instance routinely serves MANY services: the
+     * MCP server keeps a single instance per user and names the target project on every
+     * call, and the dashboard switches projects without reconstructing. A flat map let
+     * the same unique_id from two projects collide on one key, so a post carrying
+     * `reference: "src::<file>"` was silently rewritten to the OTHER project's
+     * record_id and the backend rejected it as non-existent. Never key this by
+     * unique_id alone, and never scope it by `this.service` when the call names its own.
+     */
     private __my_unique_ids;
     private __uniqueIdsPersistTimer;
     private userPool;
@@ -722,6 +744,8 @@ declare class Skapi {
                 accessToken?: boolean | string;
                 idToken?: boolean | string;
             };
+            stableGateway?: boolean;
+            revalidate?: boolean;
         }) => any;
     };
     private __connection;
@@ -1177,6 +1201,8 @@ declare class Skapi {
     config?: {
         dataType?: 'base64' | 'download' | 'endpoint' | 'blob' | 'text' | 'info';
         expires?: number;
+        browserCache?: number;
+        refresh?: boolean;
         progress?: ProgressCallback;
     }): Promise<Blob | string | void | FileInfo>;
     /**

package/dist/skapi.d.ts

@@ -51,7 +51,7 @@ type GetRecordQuery = {
     record_id?: string;
     /** Table name not required when "record_id" is given. A bare string is shorthand for { name: <string> }. */
     table?: string | {
-        /** Max 128 chars. Blocks: / ! * #, control chars, and sentinel 􏿿. */
+        /** Max 256 characters, where / ! * # % each count as 3. Blocks control chars and sentinel 􏿿. */
         name: string;
         /** Number range: 0 ~ 99. Default: 'public' */
         access_group?: number | 'private' | 'public' | 'authorized' | 'admin';
@@ -65,9 +65,9 @@ type GetRecordQuery = {
     };
     /** Index condition and range cannot be used simultaneously.*/
     index?: {
-        /** Custom names: max 128 chars, cannot start with "$", blocks / ! * #, control chars, and sentinel 􏿿. Reserved names: $uploaded, $updated, $referenced_count, $user_id. */
+        /** Custom names: max 256 characters, where / ! * # % each count as 3. Cannot start with "$". Blocks control chars and sentinel 􏿿. Reserved names: $uploaded, $updated, $referenced_count, $user_id. */
         name: string | '$updated' | '$uploaded' | '$referenced_count' | '$user_id';
-        /** String value max 256 chars. Allows punctuation (including / ! * #). Blocks control chars and sentinel 􏿿. */
+        /** String value max 256 characters. Any punctuation is allowed and counts as one character, and values compare exactly as written. Blocks control chars and sentinel 􏿿. */
         value: string | number | boolean;
         /** For a string value: '>=' = 'starts with', '<=' = 'ends with'. When the name is a compound name ending in '.', '>=' / '<=' match the child name segment (starts / ends with). '>' / '<' are lexicographic; numbers/booleans compare normally. */
         condition?: Condition;
@@ -81,7 +81,7 @@ type PostRecordConfig = {
     readonly?: boolean;
     /** Table name not required when "record_id" is given.*/
     table?: {
-        /** Max 128 chars. Blocks: / ! * #, control chars, and sentinel 􏿿. */
+        /** Max 256 characters, where / ! * # % each count as 3. Blocks control chars and sentinel 􏿿. */
         name?: string;
         /** Number range: 0 ~ 99. Default: 'public' */
         access_group?: number | 'private' | 'public' | 'authorized' | 'admin';
@@ -114,9 +114,9 @@ type PostRecordConfig = {
     reference?: string | null;
     /** null removes index */
     index?: {
-        /** Max 128 chars, cannot start with "$", blocks / ! * #, control chars, and sentinel 􏿿. */
+        /** Max 256 characters, where / ! * # % each count as 3. Cannot start with "$". Blocks control chars and sentinel 􏿿. */
         name: string;
-        /** String value max 256 chars. Allows punctuation (including / ! * #). Blocks control chars and sentinel 􏿿. */
+        /** String value max 256 characters. Any punctuation is allowed and counts as one character, and values compare exactly as written. Blocks control chars and sentinel 􏿿. */
         value: string | number | boolean;
     } | null;
     tags?: string[] | null;
@@ -176,6 +176,17 @@ type RecordData = {
     };
     ip: string;
     readonly: boolean;
+    /**
+     * Present ONLY on an element of a postRecords() result that the backend refused.
+     * Such an element is an empty record (record_id is ""), and this carries the reason
+     * the backend gave, e.g. { code: 'NOT_EXISTS', message: 'Reference "..." does not exists.' }.
+     * A saved record never has it, so `record_id` stays the test for "did this save".
+     */
+    error?: {
+        code?: string;
+        message?: string;
+        [key: string]: any;
+    };
 };
 type Connection = {
     /** User's locale */
@@ -653,6 +664,17 @@ declare class Skapi {
     owner: string;
     session: Record<string, any> | null;
     connection: Connection | null;
+    /**
+     * unique_id -> record_id, bucketed by a "<service>/<owner>" scope key.
+     *
+     * The scope is mandatory. One Skapi instance routinely serves MANY services: the
+     * MCP server keeps a single instance per user and names the target project on every
+     * call, and the dashboard switches projects without reconstructing. A flat map let
+     * the same unique_id from two projects collide on one key, so a post carrying
+     * `reference: "src::<file>"` was silently rewritten to the OTHER project's
+     * record_id and the backend rejected it as non-existent. Never key this by
+     * unique_id alone, and never scope it by `this.service` when the call names its own.
+     */
     private __my_unique_ids;
     private __uniqueIdsPersistTimer;
     private userPool;
@@ -722,6 +744,8 @@ declare class Skapi {
                 accessToken?: boolean | string;
                 idToken?: boolean | string;
             };
+            stableGateway?: boolean;
+            revalidate?: boolean;
         }) => any;
     };
     private __connection;
@@ -1177,6 +1201,8 @@ declare class Skapi {
     config?: {
         dataType?: 'base64' | 'download' | 'endpoint' | 'blob' | 'text' | 'info';
         expires?: number;
+        browserCache?: number;
+        refresh?: boolean;
         progress?: ProgressCallback;
     }): Promise<Blob | string | void | FileInfo>;
     /**