@tsg-dsp/tsg-sdk 0.0.0-stage → 0.21.0

package/dist/utils/errors.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Structured error class thrown by all SDK operations.
+ *
+ * Every `SdkError` carries a machine-readable {@link SdkErrorCode} that can be
+ * used for programmatic error handling, along with an optional HTTP
+ * `statusCode` and the original `cause`.
+ * @example
+ * ```ts
+ * import { SdkError, SdkErrorCode } from "@tsg-dsp/tsg-sdk";
+ *
+ * try {
+ *   await sdk.catalog.getDataset(id, audience);
+ * } catch (err) {
+ *   if (err instanceof SdkError && err.code === SdkErrorCode.NOT_FOUND) {
+ *     console.log("Dataset not found");
+ *   }
+ * }
+ * ```
+ */
+export declare class SdkError extends Error {
+    /** Machine-readable error code. */
+    readonly code: SdkErrorCode;
+    /** HTTP status code, when the error originated from an HTTP response. */
+    readonly statusCode?: number | undefined;
+    /** The underlying error that caused this SDK error. */
+    readonly cause?: unknown;
+    constructor(message: string, 
+    /** Machine-readable error code. */
+    code: SdkErrorCode, 
+    /** HTTP status code, when the error originated from an HTTP response. */
+    statusCode?: number | undefined, 
+    /** The underlying error that caused this SDK error. */
+    cause?: unknown);
+}
+/**
+ * Machine-readable error codes used by {@link SdkError}.
+ */
+export declare enum SdkErrorCode {
+    /** HTTP request failed */
+    REQUEST_FAILED = "REQUEST_FAILED",
+    /** Authentication failed (token acquisition, invalid credentials) */
+    AUTH_FAILED = "AUTH_FAILED",
+    /** Resource not found */
+    NOT_FOUND = "NOT_FOUND",
+    /** Polling timed out before reaching target state */
+    POLLING_TIMEOUT = "POLLING_TIMEOUT",
+    /** Invalid SDK configuration */
+    INVALID_CONFIG = "INVALID_CONFIG",
+    /** Feature not configured (e.g. wallet not configured) */
+    NOT_CONFIGURED = "NOT_CONFIGURED",
+    /** API response did not pass DTO validation */
+    VALIDATION_FAILED = "VALIDATION_FAILED"
+}
+/**
+ * Create an {@link SdkError} from an HTTP error response.
+ *
+ * Maps HTTP status codes to appropriate {@link SdkErrorCode} values:
+ * - `404` → {@link SdkErrorCode.NOT_FOUND}
+ * - `401` / `403` → {@link SdkErrorCode.AUTH_FAILED}
+ * - All others → {@link SdkErrorCode.REQUEST_FAILED}
+ * @param message - Human-readable error message.
+ * @param statusCode - The HTTP status code.
+ * @param cause - Optional underlying error.
+ * @returns A new `SdkError` instance.
+ */
+export declare function createRequestError(message: string, statusCode: number, cause?: unknown): SdkError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAG/B,mCAAmC;aACnB,IAAI,EAAE,YAAY;IAClC,yEAAyE;aACzD,UAAU,CAAC,EAAE,MAAM;IACnC,uDAAuD;aACvC,KAAK,CAAC,EAAE,OAAO;IAPjC,YACE,OAAO,EAAE,MAAM;IACf,mCAAmC;IACnB,IAAI,EAAE,YAAY;IAClC,yEAAyE;IACzD,UAAU,CAAC,EAAE,MAAM,YAAA;IACnC,uDAAuD;IACvC,KAAK,CAAC,EAAE,OAAO,EAIhC;CACF;AAED;;GAEG;AACH,oBAAY,YAAY;IACtB,0BAA0B;IAC1B,cAAc,mBAAmB;IACjC,qEAAqE;IACrE,WAAW,gBAAgB;IAC3B,yBAAyB;IACzB,SAAS,cAAc;IACvB,qDAAqD;IACrD,eAAe,oBAAoB;IACnC,gCAAgC;IAChC,cAAc,mBAAmB;IACjC,0DAA0D;IAC1D,cAAc,mBAAmB;IACjC,+CAA+C;IAC/C,iBAAiB,sBAAsB;CACxC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,OAAO,GACd,QAAQ,CAQV"}

package/dist/utils/errors.js

@@ -0,0 +1,79 @@
+/**
+ * Structured error class thrown by all SDK operations.
+ *
+ * Every `SdkError` carries a machine-readable {@link SdkErrorCode} that can be
+ * used for programmatic error handling, along with an optional HTTP
+ * `statusCode` and the original `cause`.
+ * @example
+ * ```ts
+ * import { SdkError, SdkErrorCode } from "@tsg-dsp/tsg-sdk";
+ *
+ * try {
+ *   await sdk.catalog.getDataset(id, audience);
+ * } catch (err) {
+ *   if (err instanceof SdkError && err.code === SdkErrorCode.NOT_FOUND) {
+ *     console.log("Dataset not found");
+ *   }
+ * }
+ * ```
+ */
+export class SdkError extends Error {
+    code;
+    statusCode;
+    cause;
+    constructor(message, 
+    /** Machine-readable error code. */
+    code, 
+    /** HTTP status code, when the error originated from an HTTP response. */
+    statusCode, 
+    /** The underlying error that caused this SDK error. */
+    cause) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.cause = cause;
+        this.name = "SdkError";
+    }
+}
+/**
+ * Machine-readable error codes used by {@link SdkError}.
+ */
+export var SdkErrorCode;
+(function (SdkErrorCode) {
+    /** HTTP request failed */
+    SdkErrorCode["REQUEST_FAILED"] = "REQUEST_FAILED";
+    /** Authentication failed (token acquisition, invalid credentials) */
+    SdkErrorCode["AUTH_FAILED"] = "AUTH_FAILED";
+    /** Resource not found */
+    SdkErrorCode["NOT_FOUND"] = "NOT_FOUND";
+    /** Polling timed out before reaching target state */
+    SdkErrorCode["POLLING_TIMEOUT"] = "POLLING_TIMEOUT";
+    /** Invalid SDK configuration */
+    SdkErrorCode["INVALID_CONFIG"] = "INVALID_CONFIG";
+    /** Feature not configured (e.g. wallet not configured) */
+    SdkErrorCode["NOT_CONFIGURED"] = "NOT_CONFIGURED";
+    /** API response did not pass DTO validation */
+    SdkErrorCode["VALIDATION_FAILED"] = "VALIDATION_FAILED";
+})(SdkErrorCode || (SdkErrorCode = {}));
+/**
+ * Create an {@link SdkError} from an HTTP error response.
+ *
+ * Maps HTTP status codes to appropriate {@link SdkErrorCode} values:
+ * - `404` → {@link SdkErrorCode.NOT_FOUND}
+ * - `401` / `403` → {@link SdkErrorCode.AUTH_FAILED}
+ * - All others → {@link SdkErrorCode.REQUEST_FAILED}
+ * @param message - Human-readable error message.
+ * @param statusCode - The HTTP status code.
+ * @param cause - Optional underlying error.
+ * @returns A new `SdkError` instance.
+ */
+export function createRequestError(message, statusCode, cause) {
+    if (statusCode === 404) {
+        return new SdkError(message, SdkErrorCode.NOT_FOUND, statusCode, cause);
+    }
+    if (statusCode === 401 || statusCode === 403) {
+        return new SdkError(message, SdkErrorCode.AUTH_FAILED, statusCode, cause);
+    }
+    return new SdkError(message, SdkErrorCode.REQUEST_FAILED, statusCode, cause);
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,OAAO,QAAS,SAAQ,KAAK;IAIf,IAAI;IAEJ,UAAU;IAEV,KAAK;IAPvB,YACE,OAAe;IACf,mCAAmC;IACnB,IAAkB;IAClC,yEAAyE;IACzD,UAAmB;IACnC,uDAAuD;IACvC,KAAe;QAE/B,KAAK,CAAC,OAAO,CAAC,CAAC;oBANC,IAAI;0BAEJ,UAAU;qBAEV,KAAK;QAGrB,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AAED;;GAEG;AACH,MAAM,CAAN,IAAY,YAeX;AAfD,WAAY,YAAY;IACtB,0BAA0B;IAC1B,iDAAiC,CAAA;IACjC,qEAAqE;IACrE,2CAA2B,CAAA;IAC3B,yBAAyB;IACzB,uCAAuB,CAAA;IACvB,qDAAqD;IACrD,mDAAmC,CAAA;IACnC,gCAAgC;IAChC,iDAAiC,CAAA;IACjC,0DAA0D;IAC1D,iDAAiC,CAAA;IACjC,+CAA+C;IAC/C,uDAAuC,CAAA;AACzC,CAAC,EAfW,YAAY,KAAZ,YAAY,QAevB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAe,EACf,UAAkB,EAClB,KAAe;IAEf,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;QACvB,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,SAAS,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,UAAU,KAAK,GAAG,IAAI,UAAU,KAAK,GAAG,EAAE,CAAC;QAC7C,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,WAAW,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,IAAI,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,cAAc,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;AAC/E,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./errors.js";
+export * from "./polling.js";
+export * from "./reason.js";
+export * from "./validate.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,5 @@
+export * from "./errors.js";
+export * from "./polling.js";
+export * from "./reason.js";
+export * from "./validate.js";
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC"}

package/dist/utils/polling.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Configuration for polling operations used by `waitFor*` methods.
+ */
+export interface PollingOptions {
+    /** Polling interval in milliseconds. Defaults to `1000`. */
+    intervalMs?: number;
+    /** Maximum number of polling attempts before timing out. Defaults to `20`. */
+    maxRetries?: number;
+}
+/**
+ * Poll an async function until a predicate is satisfied, or max retries are exceeded.
+ * @typeParam T - The return type of the polled function.
+ * @param fn - Async function to call on each polling attempt.
+ * @param predicate - Returns `true` when the desired state is reached.
+ * @param options - Polling interval and retry configuration.
+ * @returns The result of `fn` when `predicate` returns `true`.
+ * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.POLLING_TIMEOUT} when `maxRetries` is exceeded.
+ */
+export declare function pollUntil<T>(fn: () => Promise<T>, predicate: (result: T) => boolean, options?: PollingOptions): Promise<T>;
+//# sourceMappingURL=polling.d.ts.map

package/dist/utils/polling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polling.d.ts","sourceRoot":"","sources":["../../src/utils/polling.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAKD;;;;;;;;GAQG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAC/B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,SAAS,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,EACjC,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,CAAC,CAAC,CAkBZ"}

package/dist/utils/polling.js

@@ -0,0 +1,35 @@
+import { SdkError, SdkErrorCode } from "./errors.js";
+const DEFAULT_INTERVAL_MS = 1000;
+const DEFAULT_MAX_RETRIES = 20;
+/**
+ * Poll an async function until a predicate is satisfied, or max retries are exceeded.
+ * @typeParam T - The return type of the polled function.
+ * @param fn - Async function to call on each polling attempt.
+ * @param predicate - Returns `true` when the desired state is reached.
+ * @param options - Polling interval and retry configuration.
+ * @returns The result of `fn` when `predicate` returns `true`.
+ * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.POLLING_TIMEOUT} when `maxRetries` is exceeded.
+ */
+export async function pollUntil(fn, predicate, options) {
+    const intervalMs = options?.intervalMs ?? DEFAULT_INTERVAL_MS;
+    const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+        const result = await fn();
+        if (predicate(result)) {
+            return result;
+        }
+        if (attempt < maxRetries - 1) {
+            await delay(intervalMs);
+        }
+    }
+    throw new SdkError(`Polling timed out after ${maxRetries} attempts`, SdkErrorCode.POLLING_TIMEOUT);
+}
+/**
+ * Wait for the given number of milliseconds.
+ * @param ms - Delay duration in milliseconds.
+ * @returns A promise that resolves after the delay.
+ */
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=polling.js.map

package/dist/utils/polling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"polling.js","sourceRoot":"","sources":["../../src/utils/polling.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAYrD,MAAM,mBAAmB,GAAG,IAAI,CAAC;AACjC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAE/B;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,EAAoB,EACpB,SAAiC,EACjC,OAAwB;IAExB,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,mBAAmB,CAAC;IAC9D,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,mBAAmB,CAAC;IAE9D,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,UAAU,EAAE,OAAO,EAAE,EAAE,CAAC;QACtD,MAAM,MAAM,GAAG,MAAM,EAAE,EAAE,CAAC;QAC1B,IAAI,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC;YACtB,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,IAAI,OAAO,GAAG,UAAU,GAAG,CAAC,EAAE,CAAC;YAC7B,MAAM,KAAK,CAAC,UAAU,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,MAAM,IAAI,QAAQ,CAChB,2BAA2B,UAAU,WAAW,EAChD,YAAY,CAAC,eAAe,CAC7B,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,SAAS,KAAK,CAAC,EAAU;IACvB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/utils/reason.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Render one DSP reason value for a human-facing SDK surface.
+ *
+ * DSP reason items are arbitrary JSON values. TSG's multilingual values are
+ * rendered as their text, while peer-specific values remain inspectable JSON.
+ * @param reason - The reason value to render.
+ * @returns A human-readable representation of the value.
+ */
+export declare function formatReason(reason: unknown): string;
+/**
+ * Render all DSP reason values as one human-readable string.
+ * @param reason - The reason values to render.
+ * @returns The rendered values joined by semicolons, or undefined when absent.
+ */
+export declare function formatReasons(reason?: unknown[]): string | undefined;
+//# sourceMappingURL=reason.d.ts.map

package/dist/utils/reason.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reason.d.ts","sourceRoot":"","sources":["../../src/utils/reason.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAgBpD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,MAAM,GAAG,SAAS,CAEpE"}

package/dist/utils/reason.js

@@ -0,0 +1,34 @@
+/**
+ * Render one DSP reason value for a human-facing SDK surface.
+ *
+ * DSP reason items are arbitrary JSON values. TSG's multilingual values are
+ * rendered as their text, while peer-specific values remain inspectable JSON.
+ * @param reason - The reason value to render.
+ * @returns A human-readable representation of the value.
+ */
+export function formatReason(reason) {
+    if (typeof reason === "string") {
+        return reason;
+    }
+    if (reason !== null && typeof reason === "object") {
+        const value = reason["@value"];
+        if (typeof value === "string") {
+            return value;
+        }
+        const plainValue = reason.value;
+        if (typeof plainValue === "string") {
+            return plainValue;
+        }
+    }
+    const serialized = JSON.stringify(reason);
+    return serialized === undefined ? String(reason) : serialized;
+}
+/**
+ * Render all DSP reason values as one human-readable string.
+ * @param reason - The reason values to render.
+ * @returns The rendered values joined by semicolons, or undefined when absent.
+ */
+export function formatReasons(reason) {
+    return reason?.map(formatReason).join("; ");
+}
+//# sourceMappingURL=reason.js.map

package/dist/utils/reason.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reason.js","sourceRoot":"","sources":["../../src/utils/reason.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,MAAe;IAC1C,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAClD,MAAM,KAAK,GAAI,MAAkC,CAAC,QAAQ,CAAC,CAAC;QAC5D,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,UAAU,GAAI,MAAkC,CAAC,KAAK,CAAC;QAC7D,IAAI,OAAO,UAAU,KAAK,QAAQ,EAAE,CAAC;YACnC,OAAO,UAAU,CAAC;QACpB,CAAC;IACH,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC1C,OAAO,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;AAChE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,MAAkB;IAC9C,OAAO,MAAM,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC9C,CAAC"}

package/dist/utils/shape-validation.d.ts

@@ -0,0 +1,59 @@
+export type JsonObject = Record<string, unknown>;
+/**
+ * Validate an object response with a caller-provided type guard.
+ * @param data - Untrusted response body.
+ * @param name - Response name used in errors.
+ * @param predicate - Structural type guard.
+ * @returns The validated response.
+ */
+export declare function requireObjectResponse<T extends object>(data: unknown, name: string, predicate: (value: JsonObject) => value is JsonObject & T): T;
+/**
+ * Validate every item in an array response.
+ * @param data - Untrusted response body.
+ * @param name - Response name used in errors.
+ * @param predicate - Structural item type guard.
+ * @returns The validated response array.
+ */
+export declare function requireArrayResponse<T>(data: unknown, name: string, predicate: (value: JsonObject) => value is JsonObject & T): T[];
+/**
+ * Require an object response without accepting arrays or null.
+ * @param data - Untrusted response body.
+ * @param name - Response name used in errors.
+ * @returns The object response.
+ */
+export declare function requireObject(data: unknown, name: string): JsonObject;
+/**
+ * Check whether a value is a JSON object.
+ * @param value - Candidate value.
+ * @returns Whether the value is a non-null, non-array object.
+ */
+export declare function isObject(value: unknown): value is JsonObject;
+/**
+ * Check for a non-empty string property.
+ * @param value - Candidate object.
+ * @param key - Property name.
+ * @returns Whether the property is a non-empty string.
+ */
+export declare function hasString(value: JsonObject, key: string): boolean;
+/**
+ * Check for a finite number property.
+ * @param value - Candidate object.
+ * @param key - Property name.
+ * @returns Whether the property is a finite number.
+ */
+export declare function hasNumber(value: JsonObject, key: string): boolean;
+/**
+ * Check for a boolean property.
+ * @param value - Candidate object.
+ * @param key - Property name.
+ * @returns Whether the property is boolean.
+ */
+export declare function hasBoolean(value: JsonObject, key: string): boolean;
+/**
+ * Check for an array property and narrow its type.
+ * @param value - Candidate object.
+ * @param key - Property name.
+ * @returns Whether the property is an array.
+ */
+export declare function hasArray<K extends string>(value: JsonObject, key: K): value is JsonObject & Record<K, unknown[]>;
+//# sourceMappingURL=shape-validation.d.ts.map

package/dist/utils/shape-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape-validation.d.ts","sourceRoot":"","sources":["../../src/utils/shape-validation.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEjD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,EACpD,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,KAAK,IAAI,UAAU,GAAG,CAAC,GACxD,CAAC,CAQH;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,KAAK,IAAI,UAAU,GAAG,CAAC,GACxD,CAAC,EAAE,CAWL;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CAQrE;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAEjE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAElE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,SAAS,MAAM,EACvC,KAAK,EAAE,UAAU,EACjB,GAAG,EAAE,CAAC,GACL,KAAK,IAAI,UAAU,GAAG,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAE5C"}

package/dist/utils/shape-validation.js

@@ -0,0 +1,85 @@
+import { SdkError, SdkErrorCode } from "./errors.js";
+/**
+ * Validate an object response with a caller-provided type guard.
+ * @param data - Untrusted response body.
+ * @param name - Response name used in errors.
+ * @param predicate - Structural type guard.
+ * @returns The validated response.
+ */
+export function requireObjectResponse(data, name, predicate) {
+    if (!isObject(data) || !predicate(data)) {
+        throw new SdkError(`Invalid ${name} response`, SdkErrorCode.VALIDATION_FAILED);
+    }
+    return data;
+}
+/**
+ * Validate every item in an array response.
+ * @param data - Untrusted response body.
+ * @param name - Response name used in errors.
+ * @param predicate - Structural item type guard.
+ * @returns The validated response array.
+ */
+export function requireArrayResponse(data, name, predicate) {
+    if (!Array.isArray(data) ||
+        !data.every((item) => isObject(item) && predicate(item))) {
+        throw new SdkError(`Invalid ${name} response`, SdkErrorCode.VALIDATION_FAILED);
+    }
+    return data;
+}
+/**
+ * Require an object response without accepting arrays or null.
+ * @param data - Untrusted response body.
+ * @param name - Response name used in errors.
+ * @returns The object response.
+ */
+export function requireObject(data, name) {
+    if (!isObject(data)) {
+        throw new SdkError(`Invalid ${name} response: expected an object`, SdkErrorCode.VALIDATION_FAILED);
+    }
+    return data;
+}
+/**
+ * Check whether a value is a JSON object.
+ * @param value - Candidate value.
+ * @returns Whether the value is a non-null, non-array object.
+ */
+export function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Check for a non-empty string property.
+ * @param value - Candidate object.
+ * @param key - Property name.
+ * @returns Whether the property is a non-empty string.
+ */
+export function hasString(value, key) {
+    return typeof value[key] === "string" && value[key].length > 0;
+}
+/**
+ * Check for a finite number property.
+ * @param value - Candidate object.
+ * @param key - Property name.
+ * @returns Whether the property is a finite number.
+ */
+export function hasNumber(value, key) {
+    return typeof value[key] === "number" && Number.isFinite(value[key]);
+}
+/**
+ * Check for a boolean property.
+ * @param value - Candidate object.
+ * @param key - Property name.
+ * @returns Whether the property is boolean.
+ */
+export function hasBoolean(value, key) {
+    return typeof value[key] === "boolean";
+}
+/**
+ * Check for an array property and narrow its type.
+ * @param value - Candidate object.
+ * @param key - Property name.
+ * @returns Whether the property is an array.
+ */
+export function hasArray(value, key) {
+    return Array.isArray(value[key]);
+}
+//# sourceMappingURL=shape-validation.js.map

package/dist/utils/shape-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shape-validation.js","sourceRoot":"","sources":["../../src/utils/shape-validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAIrD;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAAa,EACb,IAAY,EACZ,SAAyD;IAEzD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,MAAM,IAAI,QAAQ,CAChB,WAAW,IAAI,WAAW,EAC1B,YAAY,CAAC,iBAAiB,CAC/B,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAa,EACb,IAAY,EACZ,SAAyD;IAEzD,IACE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QACpB,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,EACxD,CAAC;QACD,MAAM,IAAI,QAAQ,CAChB,WAAW,IAAI,WAAW,EAC1B,YAAY,CAAC,iBAAiB,CAC/B,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,IAAa,EAAE,IAAY;IACvD,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,QAAQ,CAChB,WAAW,IAAI,+BAA+B,EAC9C,YAAY,CAAC,iBAAiB,CAC/B,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,KAAiB,EAAE,GAAW;IACtD,OAAO,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AACjE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,KAAiB,EAAE,GAAW;IACtD,OAAO,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;AACvE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,KAAiB,EAAE,GAAW;IACvD,OAAO,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,SAAS,CAAC;AACzC,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CACtB,KAAiB,EACjB,GAAM;IAEN,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC;AACnC,CAAC"}

package/dist/utils/validate.d.ts

@@ -0,0 +1,47 @@
+import { ContextDto, SerializableClass } from "@tsg-dsp/common-dsp";
+import { type ClassConstructor } from "class-transformer";
+/**
+ * Infer the raw DTO type from a JSON-LD serializable class.
+ *
+ * For example, `DtoOf<Catalog>` resolves to `CatalogDto`.
+ */
+export type DtoOf<T> = T extends SerializableClass<infer DTO> ? DTO : never;
+/**
+ * Validate an API response against a DTO class.
+ *
+ * Creates a class instance from the plain data, runs `class-validator` checks,
+ * and throws a descriptive error if validation fails. Returns the transformed
+ * class instance so `class-transformer` conversions such as `Date` coercion are
+ * preserved for SDK consumers.
+ * @typeParam T - The DTO class type.
+ * @param dto - The class constructor to validate against.
+ * @param data - The plain object received from the API.
+ * @returns A validated instance of `T`.
+ * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.VALIDATION_FAILED} if validation errors are found.
+ */
+export declare function validateResponse<T extends object>(dto: ClassConstructor<T>, data: object): T;
+/**
+ * Validate an array of API responses against a DTO class.
+ *
+ * Each item is validated individually using {@link validateResponse}.
+ * @typeParam T - The DTO class type.
+ * @param dto - The class constructor to validate against.
+ * @param data - The array of plain objects received from the API.
+ * @returns An array of validated instances of `T`.
+ * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.VALIDATION_FAILED} if any item fails validation.
+ */
+export declare function validateResponseArray<T extends object>(dto: ClassConstructor<T>, data: object[]): T[];
+/**
+ * Deserialize and validate a JSON-LD API response.
+ *
+ * Uses the `@tsg-dsp/common-dsp` deserializer to convert JSON-LD payloads
+ * into typed class instances.
+ * @typeParam T - The target serializable class type.
+ * @param data - The raw JSON-LD data from the API.
+ * @param returnDto - When `true`, returns the raw DTO-shaped data instead of the deserialized class instance.
+ * @returns The deserialized class instance, or the raw DTO when `returnDto` is `true`.
+ */
+export declare function validateJsonLD<T extends SerializableClass<ContextDto>>(data: unknown, returnDto: true): Promise<DtoOf<T>>;
+export declare function validateJsonLD<T extends SerializableClass<ContextDto>>(data: unknown, returnDto?: false): Promise<T>;
+export declare function validateJsonLD<T extends SerializableClass<ContextDto>>(data: unknown, returnDto: boolean): Promise<T | DtoOf<T>>;
+//# sourceMappingURL=validate.d.ts.map

package/dist/utils/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/utils/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EAEV,iBAAiB,EAClB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAE,KAAK,gBAAgB,EAAmB,MAAM,mBAAmB,CAAC;AA6B3E;;;;GAIG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,IAAI,CAAC,SAAS,iBAAiB,CAAC,MAAM,GAAG,CAAC,GAAG,GAAG,GAAG,KAAK,CAAC;AAE5E;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAC/C,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC,EACxB,IAAI,EAAE,MAAM,GACX,CAAC,CAcH;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,EACpD,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC,EACxB,IAAI,EAAE,MAAM,EAAE,GACb,CAAC,EAAE,CAEL;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,CAAC,SAAS,iBAAiB,CAAC,UAAU,CAAC,EAC1E,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,IAAI,GACd,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AACrB,wBAAsB,cAAc,CAAC,CAAC,SAAS,iBAAiB,CAAC,UAAU,CAAC,EAC1E,IAAI,EAAE,OAAO,EACb,SAAS,CAAC,EAAE,KAAK,GAChB,OAAO,CAAC,CAAC,CAAC,CAAC;AACd,wBAAsB,cAAc,CAAC,CAAC,SAAS,iBAAiB,CAAC,UAAU,CAAC,EAC1E,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,OAAO,GACjB,OAAO,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/utils/validate.js

@@ -0,0 +1,68 @@
+import { deserialize } from "@tsg-dsp/common-dsp";
+import { plainToInstance } from "class-transformer";
+import { validateSync } from "class-validator";
+import { SdkError, SdkErrorCode } from "./errors.js";
+/**
+ * Validation error messages for a class-validator ValidationError array.
+ *
+ * Recursively traverses the ValidationError tree and returns a flat array of
+ * messages with the property path prepended to each message.
+ * @param errors - The array of ValidationError objects to process.
+ * @param parentPath - The property path of the parent object, used for recursion. Defaults to an empty string.
+ * @returns An array of strings containing the validation error messages with property paths.
+ */
+function validationMessages(errors, parentPath = "") {
+    return errors.flatMap((error) => {
+        const path = parentPath
+            ? `${parentPath}.${error.property}`
+            : error.property;
+        const ownMessages = Object.values(error.constraints ?? {}).map((message) => `${path}: ${message}`);
+        return [...ownMessages, ...validationMessages(error.children ?? [], path)];
+    });
+}
+/**
+ * Validate an API response against a DTO class.
+ *
+ * Creates a class instance from the plain data, runs `class-validator` checks,
+ * and throws a descriptive error if validation fails. Returns the transformed
+ * class instance so `class-transformer` conversions such as `Date` coercion are
+ * preserved for SDK consumers.
+ * @typeParam T - The DTO class type.
+ * @param dto - The class constructor to validate against.
+ * @param data - The plain object received from the API.
+ * @returns A validated instance of `T`.
+ * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.VALIDATION_FAILED} if validation errors are found.
+ */
+export function validateResponse(dto, data) {
+    const instance = plainToInstance(dto, data);
+    const errors = validateSync(instance, {
+        whitelist: false,
+        forbidUnknownValues: false
+    });
+    if (errors.length > 0) {
+        const messages = validationMessages(errors);
+        throw new SdkError(`Invalid ${dto.name} response: ${messages.join("; ") || "validation failed"}`, SdkErrorCode.VALIDATION_FAILED);
+    }
+    return instance;
+}
+/**
+ * Validate an array of API responses against a DTO class.
+ *
+ * Each item is validated individually using {@link validateResponse}.
+ * @typeParam T - The DTO class type.
+ * @param dto - The class constructor to validate against.
+ * @param data - The array of plain objects received from the API.
+ * @returns An array of validated instances of `T`.
+ * @throws Throws an {@link SdkError} with code {@link SdkErrorCode.VALIDATION_FAILED} if any item fails validation.
+ */
+export function validateResponseArray(dto, data) {
+    return data.map((item) => validateResponse(dto, item));
+}
+export async function validateJsonLD(data, returnDto = false) {
+    const deserialized = await deserialize(data);
+    if (returnDto) {
+        return data;
+    }
+    return deserialized;
+}
+//# sourceMappingURL=validate.js.map

package/dist/utils/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../src/utils/validate.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,WAAW,EAEZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAyB,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EAAE,YAAY,EAAwB,MAAM,iBAAiB,CAAC;AAErE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAErD;;;;;;;;GAQG;AACH,SAAS,kBAAkB,CACzB,MAAyB,EACzB,UAAU,GAAG,EAAE;IAEf,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;QAC9B,MAAM,IAAI,GAAG,UAAU;YACrB,CAAC,CAAC,GAAG,UAAU,IAAI,KAAK,CAAC,QAAQ,EAAE;YACnC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC;QACnB,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,GAAG,CAC5D,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,OAAO,EAAE,CACnC,CAAC;QACF,OAAO,CAAC,GAAG,WAAW,EAAE,GAAG,kBAAkB,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC,CAAC;IAC7E,CAAC,CAAC,CAAC;AACL,CAAC;AASD;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAC9B,GAAwB,EACxB,IAAY;IAEZ,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IAC5C,MAAM,MAAM,GAAG,YAAY,CAAC,QAAQ,EAAE;QACpC,SAAS,EAAE,KAAK;QAChB,mBAAmB,EAAE,KAAK;KAC3B,CAAC,CAAC;IACH,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,QAAQ,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAC5C,MAAM,IAAI,QAAQ,CAChB,WAAW,GAAG,CAAC,IAAI,cAAc,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,mBAAmB,EAAE,EAC7E,YAAY,CAAC,iBAAiB,CAC/B,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CACnC,GAAwB,EACxB,IAAc;IAEd,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,gBAAgB,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;AACzD,CAAC;AAwBD,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,IAAa,EACb,SAAS,GAAY,KAAK;IAE1B,MAAM,YAAY,GAAG,MAAM,WAAW,CAAI,IAAI,CAAC,CAAC;IAChD,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,IAAgB,CAAC;IAC1B,CAAC;IACD,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/dist/vendor/common-dtos/abac.policy.d.ts

@@ -0,0 +1,69 @@
+import { Action, PermissionString, RESERVED_SCOPES, Resource } from "./permissions.js";
+export type ActorType = "user" | "service" | "system";
+/** Principal kind; platform/provisioning authority is granted separately. */
+export declare const AUTHENTICATED_ACTOR_TYPES: readonly ["human", "service"];
+export type AuthenticatedActorType = (typeof AUTHENTICATED_ACTOR_TYPES)[number];
+export declare function isAuthenticatedActorType(value: unknown): value is AuthenticatedActorType;
+export interface RequestActor {
+    ownershipAliases?: string[];
+    sub: string;
+    type: ActorType;
+    actorType?: AuthenticatedActorType;
+    issuer?: string;
+    audience?: string | string[];
+    tenantId?: string;
+    authorizationRevision?: number;
+    serviceName?: string;
+    permissions?: PermissionString[];
+    didId?: string;
+    username?: string;
+    [key: string]: unknown;
+}
+export interface SubjectAttributes extends RequestActor {
+    permissions: PermissionString[];
+}
+export interface DelegationContext {
+    originalActor: RequestActor;
+    delegationChain: RequestActor[];
+    originTimestamp: Date;
+    correlationId: string;
+    effectivePermissions: PermissionString[];
+}
+export interface ResourceAttributes {
+    type: Resource;
+    id?: string;
+    ownerId?: string;
+    ownerIdentifier?: string;
+    tenantId?: string;
+    [key: string]: unknown;
+}
+export interface EnvironmentAttributes {
+    timestamp: Date;
+    ipAddress?: string;
+    userAgent?: string;
+    requestPath?: string;
+    requestMethod?: string;
+    correlationId?: string;
+    [key: string]: unknown;
+}
+export interface RequestContext {
+    caller: RequestActor;
+    delegation?: DelegationContext;
+    isOnBehalfOf: boolean;
+    environment: EnvironmentAttributes;
+}
+export interface PolicyContext {
+    subject: SubjectAttributes;
+    action: Action;
+    resource: ResourceAttributes;
+    environment: EnvironmentAttributes;
+    delegation?: DelegationContext;
+}
+export type EffectiveScope = typeof RESERVED_SCOPES.ALL | typeof RESERVED_SCOPES.OWN | "specific";
+export interface PolicyResult {
+    allowed: boolean;
+    reason?: string;
+    matchedPermission?: PermissionString;
+    effectiveScope?: EffectiveScope;
+    allowedResourceIds?: string[];
+}