@syncmatters/script-api 1.0.22 → 1.0.24

package/api.d.ts

@@ -10,7 +10,7 @@ export * from "./lib/sync.js";
 export * from "./lib/sync-group.js";
 export * from "./lib/utilities/kv-store/types.js";
 export * from "./lib/utilities/rate-limiter/rate-limiter.js";
-export type { HttpClient, HttpClientOptions, HttpRequest, } from "./lib/utilities/http-client/types.js";
+export type { HttpClient, HttpClientOptions, HttpFullResponse, HttpRequest, } from "./lib/utilities/http-client/types.js";
 export type JsonValuesReader = InstanceType<typeof JVR>;
 export type JsonValuesWriter = InstanceType<typeof JVW.JsonValuesWriter>;
 export type WriteBehaviour = JVW.WriteBehaviour;

package/lib/connection.d.ts

@@ -141,7 +141,7 @@ export interface CacheQueryOneOptions {
             name: string;
             values: string[];
         };
-        key?: string;
+        keys?: string[];
     };
     propertyFilter?: {
         metaOnly?: boolean;
@@ -292,8 +292,6 @@ export interface Row {
         srcObjectId?: string;
         srcRowId: string;
     };
-    /** if filters requested rows be returned from a 'checkpoint', the final row in the stream will return the next checkpoint here */
-    checkpoint?: string | undefined;
 }
 /** Iterator is returned in response to Query() operations  */
 export interface QueryIterator<T> extends AsyncIterableIterator<T> {
@@ -438,11 +436,11 @@ export interface ObjectSettingMeta {
     advanced?: boolean;
     readonly?: boolean;
     mandatory?: boolean;
-    displayIf?: string;
+    displayIf?: "none" | "other_setting_has_value" | "other_setting_is_not_empty";
     displayIfSetting?: string;
     displayIfValues?: string[];
-    type?: string;
-    control?: string;
+    type?: "string" | "boolean" | "number" | "string_array" | "connection_uid_template" | "google_picker";
+    control?: "singlelinetext" | "textarea" | "checkbox" | "switch" | "integer" | "url" | "datepicker" | "datetimepicker" | "filepicker" | "drivefolder" | "drivefile" | "select" | "multiselect" | "button" | "timezone";
     options?: ObjectSettingMetaOption[];
     default?: unknown;
     constraints?: ObjectFieldConstraints;
@@ -452,11 +450,6 @@ export interface ObjectSettingMetaOption {
     id: string;
     name?: string;
     order?: string;
-    /**
-     * on an option of a prerequisite (or defines_version) connection setting: `false` makes a connection
-     * with this option selected single-phase - discover() is never called and its metadata is collected on
-     * first use, as for a connector without discovery. Absent inherits the connector's `discovery` flag.
-     */
     discovery?: boolean;
 }
 export interface ObjectRowFilter {
@@ -676,7 +669,7 @@ export interface ObjectRelationship {
     data?: any;
 }
 /** IndexType holds a data index definition */
-export type IndexType = "unknown" | "jsonpath expression";
+export type IndexType = "jsonpath expression";
 /** ObjectIndex specifies an index to be added to cached connector data. */
 export interface ObjectIndex {
     name: string;

package/lib/context.d.ts

@@ -20,6 +20,18 @@ export interface Context {
     parameters: {
         [name: string]: any;
     };
+    /** set only when the run was triggered by an event */
+    event?: {
+        failedAttempts: number;
+        connectionId: string;
+        typeId: string;
+        timestamp: number;
+        object?: {
+            id: string;
+            key?: string;
+        };
+        data?: any;
+    };
     connections: ContextMapFactories<ConnectionMap, Connection>;
     syncGroups: ContextMapFactories<SyncGroupMap, SyncGroup>;
     state: {

package/lib/script-error.d.ts

@@ -15,6 +15,7 @@ export declare enum ErrorCode {
     InvalidRelationshipId = "SCRIPT_INVALID_RELATIONSHIP_ID",
     InvalidRelationshipType = "SCRIPT_INVALID_RELATIONSHIP_TYPE",
     ResourceAlreadyClosed = "SCRIPT_RESOURCE_ALREADY_CLOSED",
+    FileProviderShallowClone = "SCRIPT_FILE_PROVIDER_SHALLOW_CLONE",
     InvalidEmailRecipients = "SCRIPT_INVALID_EMAIL_RECIPIENTS",
     InvalidEmailSubject = "SCRIPT_INVALID_EMAIL_SUBJECT",
     InvalidEmailBody = "SCRIPT_INVALID_EMAIL_BODY",

package/lib/utilities/csv-reader/csv-reader-csv-parse.d.ts

@@ -9,7 +9,7 @@ export declare class CsvReaderCsvParse implements CsvReader {
     header(): Promise<string[]>;
     jsDoc(): Promise<string>;
     verifyHeader(required: string[]): Promise<void>;
-    rows(): AsyncIterableIterator<any>;
+    rows(): AsyncIterableIterator<string[]>;
     rowsWithProps(): AsyncIterableIterator<{
         [name: string]: string;
     }>;

package/lib/utilities/csv-reader/types.d.ts

@@ -26,14 +26,21 @@ export interface CsvReaderOptions {
     escapeChar?: string;
     /** number of lines to skip at the beginning of the file */
     skipLines?: number;
-    /** parse engine to use (default: 'fast-csv') */
+    /**
+     * parse engine to use (default: 'csv-parse'). 'fast-csv' was the default until csv-parse (not strict) was made to
+     * read as it does; it remains as a fallback while the switch beds in
+     */
     parseEngine?: "fast-csv" | "csv-parse";
+    /**
+     * csv-parse engine only: true rejects ragged rows, stray or misplaced quotes and whitespace-only lines, reporting
+     * the line number; false (default) tolerates them as the fast-csv engine does
+     */
+    strict?: boolean;
 }
 /**
  * CsvReader parses a csv and emits an async iterator for accessing the next row. The row is an array
- * allowing access to the fields by index or, if the csv has a header, by header name:
+ * allowing access to the fields by index, rowsWithProps allows access by header name:
  * for await (const row of reader.rows()) {
- *   var field1ByName = row["my col name"];
  *   var field1ByIndex = row[0];
  *  }
  */
@@ -41,7 +48,7 @@ export interface CsvReader {
     header(): Promise<string[]>;
     jsDoc(): Promise<string>;
     verifyHeader(required: string[]): Promise<void>;
-    rows(): AsyncIterableIterator<any>;
+    rows(): AsyncIterableIterator<string[]>;
     rowsWithProps(): AsyncIterableIterator<{
         [name: string]: string;
     }>;

package/lib/utilities/file-provider/file-provider-buffer.d.ts

@@ -1,5 +1,7 @@
 import { FileProvider } from "./file-provider.js";
+import { kIsClosed } from "./file-provider-internal.js";
 export declare class FileProviderBuffer implements FileProvider {
+    #private;
     constructor(source: Buffer);
     length(): Promise<number>;
     stream(encoding?: "utf8" | "utf16le" | "ucs2" | "latin1"): Promise<NodeJS.ReadableStream>;
@@ -7,5 +9,8 @@ export declare class FileProviderBuffer implements FileProvider {
     blob(fileName?: string): Promise<Blob>;
     save(path?: string): Promise<string>;
     close(): Promise<void>;
+    clone(): FileProviderBuffer;
+    equals(other: FileProvider): Promise<boolean>;
+    [kIsClosed](): boolean;
     toJSON(): string;
 }

package/lib/utilities/file-provider/file-provider-disk.d.ts

@@ -1,4 +1,28 @@
+import fs from "node:fs";
 import { FileProvider } from "./file-provider.js";
+import { kIsClosed } from "./file-provider-internal.js";
+/**
+ * One record per underlying file, shared by a deleteOnClose provider and every clone of it (including
+ * clones of clones). The file is unlinked when the last holder closes.
+ */
+interface SharedFile {
+    path: string;
+    holders: number;
+}
+export interface Privates {
+    file: SharedFile;
+    size?: number;
+    deleteOnClose: boolean;
+    stream: fs.ReadStream | null;
+    closed: boolean;
+}
+type Unlink = (path: string, callback: (err: NodeJS.ErrnoException | null) => void) => void;
+/**
+ * Releases a provider the runtime collected without close(): marks it closed, destroys any open stream and, for a
+ * deleteOnClose file, gives up this holder and unlinks the file when it was the last. Runs in a finalizer, so it
+ * never awaits and swallows every error; the unlink is fire-and-forget.
+ */
+export declare function releaseUnclosed(p: Privates, unlink?: Unlink): void;
 export declare class FileProviderDisk implements FileProvider {
     constructor(path: string, deleteOnClose?: boolean);
     length(): Promise<number>;
@@ -8,5 +32,9 @@ export declare class FileProviderDisk implements FileProvider {
     blob(fileName?: string): Promise<Blob>;
     save(path?: string): Promise<string>;
     close(): Promise<void>;
+    clone(): FileProviderDisk;
+    equals(other: FileProvider): Promise<boolean>;
+    [kIsClosed](): boolean;
     toJSON(): string;
 }
+export {};

package/lib/utilities/file-provider/file-provider-internal.d.ts

@@ -0,0 +1,10 @@
+import type { FileProvider } from "./file-provider.js";
+/**
+ * Internal, non-interface hook shared by the platform FileProvider classes so that equals() can
+ * tell whether the other side is closed without calling it (a closed deleteOnClose disk provider
+ * fails with ENOENT rather than ResourceAlreadyClosed). Not exported from the package.
+ */
+export declare const kIsClosed: unique symbol;
+export declare function providerIsClosed(provider: FileProvider): boolean;
+/** Compares two open providers byte for byte: length first, then both streams chunk by chunk. */
+export declare function providerBytesEqual(a: FileProvider, b: FileProvider): Promise<boolean>;

package/lib/utilities/file-provider/file-provider-shim.d.ts

@@ -0,0 +1,21 @@
+import { FileProvider } from "./file-provider.js";
+import { kIsClosed } from "./file-provider-internal.js";
+/**
+ * What utilities.clone() puts in place of a FileProvider by default. It holds no file and no state: it serialises
+ * like a provider, closes as a no-op, and every read throws a ScriptError (FileProviderShallowClone) naming the
+ * option that makes a real clone. It counts as a FileProvider (isFileProvider() is true) so that a shim which reaches
+ * a connector fails on its first read rather than being uploaded as the text "[object FileProvider]".
+ */
+export declare class FileProviderShim implements FileProvider {
+    length(): Promise<number>;
+    stream(_encoding?: "utf8" | "utf16le" | "ucs2" | "latin1"): Promise<NodeJS.ReadableStream>;
+    close(): Promise<void>;
+    save(_path?: string): Promise<string>;
+    formDataValue(_encoding?: "utf8" | "utf16le" | "ucs2" | "latin1"): Promise<unknown>;
+    blob(_fileName?: string): Promise<Blob>;
+    clone(): FileProvider;
+    equals(_other: FileProvider): Promise<boolean>;
+    /** a shim has no content, so a real provider's equals() treats it as closed and resolves false */
+    [kIsClosed](): boolean;
+    toJSON(): string;
+}

package/lib/utilities/file-provider/file-provider-string.d.ts

@@ -1,5 +1,7 @@
 import { FileProvider } from "./file-provider.js";
+import { kIsClosed } from "./file-provider-internal.js";
 export declare class FileProviderString implements FileProvider {
+    #private;
     constructor(source: string);
     length(): Promise<number>;
     stream(encoding?: "utf8" | "utf16le" | "ucs2" | "latin1"): Promise<NodeJS.ReadableStream>;
@@ -7,5 +9,8 @@ export declare class FileProviderString implements FileProvider {
     blob(fileName?: string): Promise<Blob>;
     save(path?: string): Promise<string>;
     close(): Promise<void>;
+    clone(): FileProviderString;
+    equals(other: FileProvider): Promise<boolean>;
+    [kIsClosed](): boolean;
     toJSON(): string;
 }

package/lib/utilities/file-provider/file-provider.d.ts

@@ -6,6 +6,24 @@ export interface FileProvider {
     formDataValue(encoding?: "utf8" | "utf16le" | "ucs2" | "latin1"): Promise<unknown>;
     blob(fileName?: string): Promise<Blob>;
     toJSON(): string;
+    /**
+     * Returns an independent provider over the same bytes. The clone must be closed like any other
+     * provider: closing the original does not close the clone, and closing the clone does not close
+     * the original. A clone of a string or buffer provider re-wraps the source (no disk is shared).
+     * A clone of a disk provider created with deleteOnClose shares the underlying file by reference
+     * count: the file is removed only when the original and every clone of it have been closed. A
+     * provider dropped without close is released when the runtime collects it, which may be much later.
+     * utilities.clone(value, { withFileProviders: true }) calls this for every provider in value; the
+     * default utilities.clone(value) does not, and puts a shallow-clone shim in its place.
+     * Throws ResourceAlreadyClosed when this provider has been closed.
+     */
+    clone(): FileProvider;
+    /**
+     * Resolves true when both providers hold the same bytes. Compares length() first, then streams both
+     * and compares chunk by chunk without buffering whole files. Resolves false, rather than throwing,
+     * when either side has been closed.
+     */
+    equals(other: FileProvider): Promise<boolean>;
 }
 export interface FileProviderOptions {
     file?: {
@@ -18,4 +36,10 @@ export interface FileProviderOptions {
 export declare function fileProvider(options: FileProviderOptions): FileProvider;
 export declare namespace fileProvider {
     var isFileProvider: (value: unknown) => value is FileProvider;
+    var closeAll: typeof closeFileProviders;
 }
+/**
+ * Closes every FileProvider found in value, walking plain objects and arrays. Close errors are swallowed: this is
+ * for releasing providers the caller owns (for example the clones inside a snapshot) once it is done with them.
+ */
+export declare function closeFileProviders(value: unknown): Promise<void>;

package/lib/utilities/http-client/types.d.ts

@@ -36,6 +36,14 @@ export interface HttpRequest {
     fullResponse?: boolean;
     fileResponse?: boolean;
 }
+/** HttpFullResponse is the execute() response when HttpRequest option fullResponse is true */
+export interface HttpFullResponse {
+    body?: any;
+    headers: {
+        [name: string]: string;
+    };
+    statusCode: number;
+}
 /** HttpCanRetry is an optional interface allowing a connector to assess whether a retry is allowed */
 export interface HttpCanRetry {
     (err: HttpError, method: HttpMethod, url: string, httpCode: number, responseHeaders: {
@@ -55,7 +63,6 @@ export interface HttpClientOptions {
     errMessageFormat?: "default" | "concise";
     canRetry?: HttpCanRetry;
     onError?: (err: HttpError, method: HttpMethod, url: string, httpCode: number, reqJson?: unknown) => void;
-    onSuccess?: (method: string, url: string, httpCode: number, reqJson?: unknown) => void;
 }
 export interface HttpClient {
     execute: (request: HttpRequest) => Promise<any>;

package/lib/utilities/utilities.d.ts

@@ -21,10 +21,24 @@ import * as TypeUtils from "./type-utils/type-utils.js";
 import * as JsonUtils from "./json-utils/index.js";
 import * as UpsertFlags from "./upsert-flags/upsert-flags.js";
 import { KvStore } from "@syncmatters/script-api";
+export interface CloneOptions {
+    /**
+     * Clone each FileProvider with FileProvider.clone(), so the copy can read the file. Each cloned provider must be
+     * closed like any other. Without this, each provider in the copy is a shallow-clone shim.
+     */
+    withFileProviders?: boolean;
+}
+/**
+ * Deep copy. By default each FileProvider in value is replaced with a shallow-clone shim: it serialises like a
+ * provider and needs no close, but any read throws (ErrorCode.FileProviderShallowClone). That suits a snapshot for
+ * logging or tracing. Pass { withFileProviders: true } to clone the providers too (see FileProvider.clone()): the copy
+ * can read the files and each cloned provider must be closed.
+ */
+declare function clone<T>(value: T, options?: CloneOptions): T;
 export declare const utilities: {
     arrayOfStr: typeof arrayOfStrings;
     arrayOfNum: typeof arrayOfNumbers;
-    clone: <T>(value: T) => T;
+    clone: typeof clone;
     csvReader: (options: CsvReaderOptions) => import("./csv-reader/types.js").CsvReader;
     csvWriter: (options: CsvWriterOptions) => CsvWriter;
     dateFormat: typeof dateFormat;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncmatters/script-api",
-  "version": "1.0.22",
+  "version": "1.0.24",
   "description": "TypeScript type definitions for the SyncMatters script API (types only - scripts execute on the SyncMatters platform)",
   "types": "./index.d.ts",
   "exports": {
@@ -28,7 +28,7 @@
   "license": "MIT",
   "author": "SyncMatters",
   "homepage": "https://syncmatters.com",
-  "typesContentHash": "b96f39108ef358c683102abb6eaeae9b47358feb140dcdc03fea91f41410102a",
+  "typesContentHash": "f3ff131064f3d7de6653d9bb2a7766b1ea8e918cd38aacbf0f73e6b37dfe13f8",
   "dependencies": {
     "@types/node": "*"
   }

package/sdk-test/sdk-test.d.ts

@@ -373,6 +373,13 @@ export interface UpsertOptions {
     meta: API.ObjectMeta;
     withIssueSimulators?: boolean;
     withUpsertFieldOptions?: API.JsonValuePath;
+    /**
+     * Path of a file field (`type: "file"`) on the object's upsert fields that the returned insert and update data
+     * should populate with a FileProvider. The harness sends it on the upsert and delete tests' prepare calls whenever
+     * the object has a file field, preferring one with `constraints.mandatory: "add"`; a hook that ignores it loses
+     * nothing. It is sent on every upsertPrepare call whenever the object has a file field, including the upsertClean
+     * test's (the one with `withIssueSimulators`).
+     */
     withFileField?: API.JsonValuePath;
 }
 /** Options passed when cleaning up after an upsert test. */
@@ -382,13 +389,25 @@ export interface UpsertCleanupOptions {
 }
 /** Data returned when requesting data that will be used for an upsert test. */
 export interface UpsertData {
-    /** data to pass in the upsert call (ideally for an add operation) */
+    /**
+     * data to pass in the upsert call (ideally for an add operation). Return a fresh FileProvider in each call: the
+     * harness passes the connector a clone (`API.utilities.clone(insert, { withFileProviders: true })`, so each provider
+     * is a readable clone) and closes the originals and its clones after verifying.
+     */
     insert?: unknown;
-    /** a simple update that may be made to the added row (the test harness will copy over the key from the add response) */
+    /**
+     * a simple update that may be made to the added row (the test harness will copy over the key from the add response).
+     * FileProviders here follow the same rule as `insert`: fresh per call, cloned before writing, closed after verifying.
+     */
     update?: unknown;
     /** if requested, include 'bad data' examples that will trigger upsertClean issues */
     issueSimulators?: Array<UpsertIssueSimulator>;
-    /** fields to check to verify the insert/update was successful */
+    /**
+     * fields to check to verify the insert/update was successful. The same paths are checked on the update row, so a
+     * listed field must be set in both `insert` and `update`. A file field compares by bytes through
+     * `FileProvider.equals()`: the queried value must be a FileProvider holding the same content. Listing a file field
+     * here (or in `fields`) makes the query-back download its content; the harness never adds it on its own.
+     */
     verifyFields?: Array<API.JsonValuePath>;
     /** optionally specify other fields to include when querying the data back for validation */
     fields?: Array<API.JsonValuePath>;