@proveanything/smartlinks 1.2.3 → 1.3.1

package/dist/http.js

@@ -2,6 +2,18 @@
 // This module replaces the ApiClient constructor. It keeps baseURL, apiKey, bearerToken
 // in module-scope variables, and provides a shared `request<T>(path)` helper that will
 // be used by all namespaced files (collection.ts, product.ts, etc.).
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+import { SmartlinksApiError } from "./types/error";
 let baseURL = null;
 let apiKey = undefined;
 let bearerToken = undefined;
@@ -63,6 +75,88 @@ function safeBodyPreview(body) {
     }
     return body;
 }
+/**
+ * Normalizes various server error response formats into a consistent ErrorResponse shape.
+ * Handles multiple formats:
+ * - { code: number, message: string } (standard)
+ * - { errorCode: string, errorText: string }
+ * - { error: string, message: string }
+ * - { error: string } (just error field)
+ * - { ok: false, error: string }
+ * - Plain string
+ *
+ * @param responseBody - The parsed JSON response body from the server
+ * @param statusCode - HTTP status code
+ * @returns Normalized ErrorResponse object
+ */
+function normalizeErrorResponse(responseBody, statusCode) {
+    if (!responseBody || typeof responseBody !== 'object') {
+        // Plain string or non-object response
+        const message = typeof responseBody === 'string' ? responseBody : 'Request failed';
+        return {
+            code: statusCode,
+            message,
+        };
+    }
+    // Extract all possible fields from the response
+    const { code, errorCode, error, message, errorText, ok } = responseBody, rest = __rest(responseBody
+    // Determine the error code (prefer numeric code, fall back to errorCode or error string)
+    , ["code", "errorCode", "error", "message", "errorText", "ok"]);
+    // Determine the error code (prefer numeric code, fall back to errorCode or error string)
+    let normalizedCode = statusCode;
+    if (typeof code === 'number') {
+        normalizedCode = code;
+    }
+    else if (typeof errorCode === 'string' || typeof error === 'string') {
+        // Keep statusCode as numeric code, but preserve the string code in details
+    }
+    // Determine the error message
+    let normalizedMessage;
+    if (message) {
+        normalizedMessage = String(message);
+    }
+    else if (errorText) {
+        normalizedMessage = String(errorText);
+    }
+    else if (error) {
+        normalizedMessage = String(error);
+    }
+    else if (ok === false) {
+        normalizedMessage = 'Request failed';
+    }
+    else {
+        normalizedMessage = `Request failed with status ${statusCode}`;
+    }
+    // Extract the server-specific error code string (distinct from HTTP status code)
+    let normalizedErrorCode;
+    if (errorCode && typeof errorCode === 'string') {
+        normalizedErrorCode = errorCode;
+    }
+    else if (error && typeof error === 'string') {
+        normalizedErrorCode = error;
+    }
+    // Collect any additional details
+    const details = Object.assign({}, rest);
+    // Preserve error fields in details for backward compatibility
+    if (errorCode && typeof errorCode === 'string') {
+        details.errorCode = errorCode;
+    }
+    if (error && typeof error === 'string') {
+        details.error = error;
+    }
+    if (errorText && errorText !== normalizedMessage) {
+        details.errorText = errorText;
+    }
+    if (ok === false) {
+        details.ok = ok;
+    }
+    return {
+        code: normalizedCode,
+        errorCode: normalizedErrorCode,
+        message: normalizedMessage,
+        details: Object.keys(details).length > 0 ? details : undefined,
+    };
+}
 /**
  * Call this once (e.g. at app startup) to configure baseURL/auth.
  *
@@ -336,14 +430,18 @@ export async function request(path) {
     });
     logDebug('[smartlinks] GET response', { url, status: response.status, ok: response.ok });
     if (!response.ok) {
-        // Try to parse ErrorResponse; if that fails, throw generic
+        // Try to parse error response body and normalize it
+        let responseBody;
         try {
-            const errBody = (await response.json());
-            throw new Error(`Error ${errBody.code}: ${errBody.message}`);
+            responseBody = await response.json();
         }
         catch (_a) {
-            throw new Error(`Request to ${url} failed with status ${response.status}`);
+            // Failed to parse JSON, use status code only
+            responseBody = null;
         }
+        const errBody = normalizeErrorResponse(responseBody, response.status);
+        const message = `Error ${errBody.code}: ${errBody.message}`;
+        throw new SmartlinksApiError(message, response.status, errBody, url);
     }
     return (await response.json());
 }
@@ -384,13 +482,16 @@ export async function post(path, body, extraHeaders) {
     });
     logDebug('[smartlinks] POST response', { url, status: response.status, ok: response.ok });
     if (!response.ok) {
+        let responseBody;
         try {
-            const errBody = (await response.json());
-            throw new Error(`Error ${errBody.code}: ${errBody.message}`);
+            responseBody = await response.json();
         }
         catch (_a) {
-            throw new Error(`Request to ${url} failed with status ${response.status}`);
+            responseBody = null;
         }
+        const errBody = normalizeErrorResponse(responseBody, response.status);
+        const message = `Error ${errBody.code}: ${errBody.message}`;
+        throw new SmartlinksApiError(message, response.status, errBody, url);
     }
     return (await response.json());
 }
@@ -431,13 +532,16 @@ export async function put(path, body, extraHeaders) {
     });
     logDebug('[smartlinks] PUT response', { url, status: response.status, ok: response.ok });
     if (!response.ok) {
+        let responseBody;
         try {
-            const errBody = (await response.json());
-            throw new Error(`Error ${errBody.code}: ${errBody.message}`);
+            responseBody = await response.json();
         }
         catch (_a) {
-            throw new Error(`Request to ${url} failed with status ${response.status}`);
+            responseBody = null;
         }
+        const errBody = normalizeErrorResponse(responseBody, response.status);
+        const message = `Error ${errBody.code}: ${errBody.message}`;
+        throw new SmartlinksApiError(message, response.status, errBody, url);
     }
     return (await response.json());
 }
@@ -478,13 +582,16 @@ export async function patch(path, body, extraHeaders) {
     });
     logDebug('[smartlinks] PATCH response', { url, status: response.status, ok: response.ok });
     if (!response.ok) {
+        let responseBody;
         try {
-            const errBody = (await response.json());
-            throw new Error(`Error ${errBody.code}: ${errBody.message}`);
+            responseBody = await response.json();
         }
         catch (_a) {
-            throw new Error(`Request to ${url} failed with status ${response.status}`);
+            responseBody = null;
         }
+        const errBody = normalizeErrorResponse(responseBody, response.status);
+        const message = `Error ${errBody.code}: ${errBody.message}`;
+        throw new SmartlinksApiError(message, response.status, errBody, url);
     }
     return (await response.json());
 }
@@ -528,13 +635,16 @@ export async function requestWithOptions(path, options) {
     const response = await fetch(url, Object.assign(Object.assign({}, options), { headers }));
     logDebug('[smartlinks] requestWithOptions response', { url, status: response.status, ok: response.ok });
     if (!response.ok) {
+        let responseBody;
         try {
-            const errBody = (await response.json());
-            throw new Error(`Error ${errBody.code}: ${errBody.message}`);
+            responseBody = await response.json();
         }
         catch (_a) {
-            throw new Error(`Request to ${url} failed with status ${response.status}`);
+            responseBody = null;
         }
+        const errBody = normalizeErrorResponse(responseBody, response.status);
+        const message = `Error ${errBody.code}: ${errBody.message}`;
+        throw new SmartlinksApiError(message, response.status, errBody, url);
     }
     return (await response.json());
 }
@@ -569,13 +679,16 @@ export async function del(path, extraHeaders) {
     });
     logDebug('[smartlinks] DELETE response', { url, status: response.status, ok: response.ok });
     if (!response.ok) {
+        let responseBody;
         try {
-            const errBody = (await response.json());
-            throw new Error(`Error ${errBody.code}: ${errBody.message}`);
+            responseBody = await response.json();
         }
         catch (_a) {
-            throw new Error(`Request to ${url} failed with status ${response.status}`);
+            responseBody = null;
         }
+        const errBody = normalizeErrorResponse(responseBody, response.status);
+        const message = `Error ${errBody.code}: ${errBody.message}`;
+        throw new SmartlinksApiError(message, response.status, errBody, url);
     }
     // If the response is empty, just return undefined
     if (response.status === 204)

package/dist/types/asset.d.ts

@@ -85,6 +85,8 @@ export interface UploadAssetOptions {
     onProgress?: (percent: number) => void;
     /** Optional: App ID for scoping to a specific microapp */
     appId?: string;
+    /** Optional: Upload via admin route instead of public */
+    admin?: boolean;
 }
 export interface ListAssetsOptions {
     scope: {

package/dist/types/error.d.ts

@@ -1,9 +1,75 @@
 /**
- * Represents a standardized error response.
+ * Represents a standardized error response from the server.
  */
 export interface ErrorResponse {
-    /** Numeric error code */
+    /** Numeric error code (typically the HTTP status code: 400, 401, 500, etc.) */
     code: number;
-    /** Human-readable error message */
+    /** Server-specific error code string (e.g., "NOT_AUTHORIZED", "broadcasts.topic.invalid") */
+    errorCode?: string;
+    /** Human-readable error message in English (should be translated/customized by the application) */
     message: string;
+    /** Additional error details from the server (optional) */
+    details?: Record<string, any>;
+}
+/**
+ * SDK error class that preserves all error context from HTTP responses.
+ * Provides programmatic access to status codes, error codes, and response details.
+ *
+ * Important: Server-defined string error codes (e.g., "NOT_AUTHORIZED", "broadcasts.topic.invalid")
+ * are preserved in the `details` property, not in the numeric `code` property.
+ */
+export declare class SmartlinksApiError extends Error {
+    readonly statusCode: number;
+    readonly errorResponse?: ErrorResponse | undefined;
+    readonly url?: string | undefined;
+    /**
+     * @param message - Human-readable error message (English text from server)
+     * @param statusCode - HTTP status code (e.g., 400, 401, 500)
+     * @param errorResponse - Parsed error response from the server (if available)
+     * @param url - The URL that was requested
+     */
+    constructor(message: string, statusCode: number, errorResponse?: ErrorResponse | undefined, url?: string | undefined);
+    /**
+     * Returns the numeric error code from the server response, if available.
+     * This is typically the HTTP status code (400, 401, 500, etc.).
+     *
+     * For server-defined string error codes like "NOT_AUTHORIZED" or "broadcasts.topic.invalid",
+     * use: `error.details?.errorCode || error.details?.error`
+     */
+    get code(): number | undefined;
+    /**
+     * Returns the server-specific error code string.
+     * This is distinct from the HTTP status code (e.g., "NOT_AUTHORIZED", "broadcasts.topic.invalid").
+     * This is the primary identifier to check for programmatic error handling.
+     */
+    get errorCode(): string | undefined;
+    /**
+     * Returns additional error details from the server, if available.
+     * This object contains various server-specific fields that may vary by endpoint.
+     */
+    get details(): Record<string, any> | undefined;
+    /**
+     * Check if this is a client error (4xx status code).
+     */
+    isClientError(): boolean;
+    /**
+     * Check if this is a server error (5xx status code).
+     */
+    isServerError(): boolean;
+    /**
+     * Check if this is an authentication error (401 or 403).
+     */
+    isAuthError(): boolean;
+    /**
+     * Check if this is a not found error (404).
+     */
+    isNotFound(): boolean;
+    /**
+     * Check if this is a rate limit error (429).
+     */
+    isRateLimited(): boolean;
+    /**
+     * Returns a JSON representation of the error for logging/debugging.
+     */
+    toJSON(): Record<string, any>;
 }

package/dist/types/error.js

@@ -1 +1,98 @@
-export {};
+/**
+ * SDK error class that preserves all error context from HTTP responses.
+ * Provides programmatic access to status codes, error codes, and response details.
+ *
+ * Important: Server-defined string error codes (e.g., "NOT_AUTHORIZED", "broadcasts.topic.invalid")
+ * are preserved in the `details` property, not in the numeric `code` property.
+ */
+export class SmartlinksApiError extends Error {
+    /**
+     * @param message - Human-readable error message (English text from server)
+     * @param statusCode - HTTP status code (e.g., 400, 401, 500)
+     * @param errorResponse - Parsed error response from the server (if available)
+     * @param url - The URL that was requested
+     */
+    constructor(message, statusCode, errorResponse, url) {
+        super(message);
+        this.statusCode = statusCode;
+        this.errorResponse = errorResponse;
+        this.url = url;
+        this.name = 'SmartlinksApiError';
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, SmartlinksApiError);
+        }
+    }
+    /**
+     * Returns the numeric error code from the server response, if available.
+     * This is typically the HTTP status code (400, 401, 500, etc.).
+     *
+     * For server-defined string error codes like "NOT_AUTHORIZED" or "broadcasts.topic.invalid",
+     * use: `error.details?.errorCode || error.details?.error`
+     */
+    get code() {
+        var _a;
+        return (_a = this.errorResponse) === null || _a === void 0 ? void 0 : _a.code;
+    }
+    /**
+     * Returns the server-specific error code string.
+     * This is distinct from the HTTP status code (e.g., "NOT_AUTHORIZED", "broadcasts.topic.invalid").
+     * This is the primary identifier to check for programmatic error handling.
+     */
+    get errorCode() {
+        var _a;
+        return (_a = this.errorResponse) === null || _a === void 0 ? void 0 : _a.errorCode;
+    }
+    /**
+     * Returns additional error details from the server, if available.
+     * This object contains various server-specific fields that may vary by endpoint.
+     */
+    get details() {
+        var _a;
+        return (_a = this.errorResponse) === null || _a === void 0 ? void 0 : _a.details;
+    }
+    /**
+     * Check if this is a client error (4xx status code).
+     */
+    isClientError() {
+        return this.statusCode >= 400 && this.statusCode < 500;
+    }
+    /**
+     * Check if this is a server error (5xx status code).
+     */
+    isServerError() {
+        return this.statusCode >= 500 && this.statusCode < 600;
+    }
+    /**
+     * Check if this is an authentication error (401 or 403).
+     */
+    isAuthError() {
+        return this.statusCode === 401 || this.statusCode === 403;
+    }
+    /**
+     * Check if this is a not found error (404).
+     */
+    isNotFound() {
+        return this.statusCode === 404;
+    }
+    /**
+     * Check if this is a rate limit error (429).
+     */
+    isRateLimited() {
+        return this.statusCode === 429;
+    }
+    /**
+     * Returns a JSON representation of the error for logging/debugging.
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            statusCode: this.statusCode,
+            code: this.code,
+            errorCode: this.errorCode,
+            details: this.details,
+            url: this.url,
+        };
+    }
+}

package/dist/types/index.d.ts

@@ -21,3 +21,4 @@ export * from "./template";
 export * from "./interaction";
 export * from "./location";
 export * from "./jobs";
+export * from "./realtime";

package/dist/types/index.js

@@ -23,3 +23,4 @@ export * from "./template";
 export * from "./interaction";
 export * from "./location";
 export * from "./jobs";
+export * from "./realtime";

package/dist/types/realtime.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Request parameters for obtaining a realtime token.
+ */
+export interface RealtimeTokenRequest {
+    /** Required - the collection scope */
+    collectionId: string;
+    /** Optional - scope to specific app */
+    appId?: string;
+}
+/**
+ * Ably token request response for real-time communications.
+ * This token can be used to initialize an Ably client with appropriate permissions.
+ */
+export interface AblyTokenRequest {
+    /** Ably key name */
+    keyName: string;
+    /** Token time-to-live in milliseconds */
+    ttl: number;
+    /** Request timestamp */
+    timestamp: number;
+    /** JSON string of channel permissions */
+    capability: string;
+    /** Random nonce */
+    nonce: string;
+    /** Message authentication code */
+    mac: string;
+    /** Client identifier: "collectionId:userId:appId?" */
+    clientId: string;
+}
+/**
+ * Channel patterns for real-time communications:
+ *
+ * With appId: collection:{collectionId}:app:{appId}:*
+ * Examples:
+ *   - collection:abc:app:xyz:chat:room-1
+ *   - collection:abc:app:xyz:notifications:alerts
+ *   - collection:abc:app:xyz:users:online
+ *
+ * Without appId: collection:{collectionId}:*
+ * Examples:
+ *   - collection:abc:events:updates
+ *   - collection:abc:users:active
+ */
+export type RealtimeChannelPattern = string;

package/dist/types/realtime.js

@@ -0,0 +1,2 @@
+// src/types/realtime.ts
+export {};

package/package.json

@@ -1,16 +1,15 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.2.3",
+  "version": "1.3.1",
   "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
     "dist/",
-    "README.md",
-    "API_SUMMARY.md"
+    "README.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && node scripts/copy-docs-to-dist.js",
     "docs": "typedoc",
     "docs:summary": "node generate-api-summary.js",
     "build:docs": "tsc build-docs.ts --outDir dist && node dist/build-docs.js",

package/dist/api/actions.d.ts

@@ -1,32 +0,0 @@
-import type { ActionQueryByUser, ActionCountsQuery, ActorIdsByActionQuery, AppendActionBody, OutcomeCount, ActorId, ActorWithOutcome, ActionEventRow, AdminByUserRequest, AdminCountsByOutcomeRequest, AdminActorIdsByActionRequest, PublicCountsByOutcomeRequest, PublicByUserRequest, CreateActionBody, UpdateActionBody, ListActionsQuery, ActionRecord, ActionList } from "../types/actions";
-export declare namespace actions {
-    /**
-     * POST /admin/collection/:collectionId/actions/by-user
-     * Returns BigQuery action rows, newest first.
-     */
-    function byUser(collectionId: string, query?: AdminByUserRequest | ActionQueryByUser): Promise<ActionEventRow[]>;
-    /**
-     * POST /admin/collection/:collectionId/actions/counts-by-outcome
-     * Returns array of { outcome, count }.
-     */
-    function countsByOutcome(collectionId: string, query?: AdminCountsByOutcomeRequest | ActionCountsQuery): Promise<OutcomeCount[]>;
-    /**
-     * POST /admin/collection/:collectionId/actions/actor-ids/by-action
-     * Returns list of IDs, optionally with outcome when includeOutcome=true.
-     */
-    function actorIdsByAction(collectionId: string, query: AdminActorIdsByActionRequest | ActorIdsByActionQuery): Promise<ActorId[] | ActorWithOutcome[]>;
-    /**
-     * POST /admin/collection/:collectionId/actions/append
-     * Appends one action event.
-     */
-    function append(collectionId: string, body: AppendActionBody): Promise<{
-        success: true;
-    }>;
-    function create(collectionId: string, body: CreateActionBody): Promise<ActionRecord>;
-    function list(collectionId: string, query?: ListActionsQuery): Promise<ActionList>;
-    function get(collectionId: string, id: string): Promise<ActionRecord>;
-    function update(collectionId: string, id: string, patchBody: UpdateActionBody): Promise<ActionRecord>;
-    function remove(collectionId: string, id: string): Promise<void>;
-    function publicCountsByOutcome(collectionId: string, body: PublicCountsByOutcomeRequest, authToken?: string): Promise<OutcomeCount[]>;
-    function publicMyActions(collectionId: string, body: PublicByUserRequest, authToken?: string): Promise<ActionEventRow[]>;
-}

package/dist/api/actions.js

@@ -1,99 +0,0 @@
-// src/api/actions.ts
-import { request, post, patch, del } from "../http";
-function encodeQuery(params) {
-    const search = new URLSearchParams();
-    for (const [key, value] of Object.entries(params)) {
-        if (value === undefined || value === null || value === "")
-            continue;
-        if (typeof value === "boolean") {
-            search.set(key, value ? "true" : "false");
-        }
-        else {
-            search.set(key, String(value));
-        }
-    }
-    const qs = search.toString();
-    return qs ? `?${qs}` : "";
-}
-export var actions;
-(function (actions) {
-    /**
-     * POST /admin/collection/:collectionId/actions/by-user
-     * Returns BigQuery action rows, newest first.
-     */
-    async function byUser(collectionId, query = {}) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/actions/by-user`;
-        return post(path, query);
-    }
-    actions.byUser = byUser;
-    /**
-     * POST /admin/collection/:collectionId/actions/counts-by-outcome
-     * Returns array of { outcome, count }.
-     */
-    async function countsByOutcome(collectionId, query = {}) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/actions/counts-by-outcome`;
-        return post(path, query);
-    }
-    actions.countsByOutcome = countsByOutcome;
-    /**
-     * POST /admin/collection/:collectionId/actions/actor-ids/by-action
-     * Returns list of IDs, optionally with outcome when includeOutcome=true.
-     */
-    async function actorIdsByAction(collectionId, query) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/actions/actor-ids/by-action`;
-        return post(path, query);
-    }
-    actions.actorIdsByAction = actorIdsByAction;
-    /**
-     * POST /admin/collection/:collectionId/actions/append
-     * Appends one action event.
-     */
-    async function append(collectionId, body) {
-        if (!body.userId && !body.contactId) {
-            throw new Error("AppendActionBody must include one of userId or contactId");
-        }
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/actions/append`;
-        return post(path, body);
-    }
-    actions.append = append;
-    // CRUD: Actions (Postgres)
-    async function create(collectionId, body) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/actions/`;
-        return post(path, body);
-    }
-    actions.create = create;
-    async function list(collectionId, query = {}) {
-        const qs = encodeQuery(query);
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/actions/${qs}`;
-        return request(path);
-    }
-    actions.list = list;
-    async function get(collectionId, id) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/actions/${encodeURIComponent(id)}`;
-        return request(path);
-    }
-    actions.get = get;
-    async function update(collectionId, id, patchBody) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/actions/${encodeURIComponent(id)}`;
-        return patch(path, patchBody);
-    }
-    actions.update = update;
-    async function remove(collectionId, id) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/actions/${encodeURIComponent(id)}`;
-        return del(path);
-    }
-    actions.remove = remove;
-    // Public endpoints (permission-aware)
-    async function publicCountsByOutcome(collectionId, body, authToken) {
-        const path = `/public/collection/${encodeURIComponent(collectionId)}/actions/counts-by-outcome`;
-        const headers = authToken ? { AUTHORIZATION: `Bearer ${authToken}` } : undefined;
-        return post(path, body, headers);
-    }
-    actions.publicCountsByOutcome = publicCountsByOutcome;
-    async function publicMyActions(collectionId, body, authToken) {
-        const path = `/public/collection/${encodeURIComponent(collectionId)}/actions/by-user`;
-        const headers = authToken ? { AUTHORIZATION: `Bearer ${authToken}` } : undefined;
-        return post(path, body, headers);
-    }
-    actions.publicMyActions = publicMyActions;
-})(actions || (actions = {}));