@proveanything/smartlinks 1.3.34 → 1.3.37

package/dist/api/appConfiguration.d.ts

@@ -1,24 +1,301 @@
 import { CollectionWidgetsResponse, GetCollectionWidgetsOptions } from "../types/appManifest";
+/**
+ * Options for collection/product-scoped app configuration.
+ * This data is set by admins and applies to all users within the scope.
+ */
 export type AppConfigOptions = {
+    /** The app ID */
     appId: string;
+    /** Collection ID (required for most operations) */
     collectionId?: string;
+    /** Product ID (optional - for product-scoped config) */
     productId?: string;
+    /** Variant ID (optional - for variant-scoped config) */
     variantId?: string;
+    /** Batch ID (optional - for batch-scoped config) */
     batchId?: string;
+    /** Item ID - required for getDataItem/deleteDataItem */
     itemId?: string;
-    user?: boolean;
-    userData?: boolean;
+    /** Use admin endpoints instead of public */
     admin?: boolean;
+    /** Configuration object for setConfig */
     config?: any;
+    /** Data object for setDataItem */
     data?: any;
 };
+/**
+ * User-specific app data storage.
+ * This data is global per user+app and shared across all collections.
+ * Perfect for personal preferences, settings, and user-generated content.
+ *
+ * @example
+ * ```typescript
+ * // Store user's garden bed layout
+ * await userAppData.set('garden-planner', {
+ *   id: 'bed-1',
+ *   name: 'Vegetable Bed',
+ *   plants: ['tomatoes', 'peppers']
+ * });
+ *
+ * // Get all user's data for this app
+ * const beds = await userAppData.list('garden-planner');
+ *
+ * // Get specific item
+ * const bed = await userAppData.get('garden-planner', 'bed-1');
+ *
+ * // Remove item
+ * await userAppData.remove('garden-planner', 'bed-1');
+ * ```
+ */
+export declare namespace userAppData {
+    /**
+     * Get user's config blob for an app.
+     * This is a single JSON object stored per user+app.
+     *
+     * @param appId - The app ID
+     * @returns The user's config object
+     *
+     * @example
+     * ```typescript
+     * const config = await userAppData.getConfig('allergy-tracker');
+     * // Returns: { allergies: ['peanuts'], notifications: true }
+     * ```
+     */
+    function getConfig(appId: string): Promise<any>;
+    /**
+     * Set user's config blob for an app.
+     *
+     * @param appId - The app ID
+     * @param config - The config object to store
+     *
+     * @example
+     * ```typescript
+     * await userAppData.setConfig('allergy-tracker', {
+     *   allergies: ['peanuts', 'shellfish'],
+     *   notifications: true
+     * });
+     * ```
+     */
+    function setConfig(appId: string, config: any): Promise<any>;
+    /**
+     * Delete user's config blob for an app.
+     *
+     * @param appId - The app ID
+     *
+     * @example
+     * ```typescript
+     * await userAppData.deleteConfig('allergy-tracker');
+     * ```
+     */
+    function deleteConfig(appId: string): Promise<void>;
+    /**
+     * List all user's data items for an app.
+     * Returns an array of objects, each with an `id` field.
+     *
+     * @param appId - The app ID
+     * @returns Array of data items
+     *
+     * @example
+     * ```typescript
+     * const beds = await userAppData.list('garden-planner');
+     * // Returns: [{ id: 'bed-1', name: 'Vegetables', ... }, { id: 'bed-2', ... }]
+     * ```
+     */
+    function list(appId: string): Promise<any[]>;
+    /**
+     * Get a specific user data item by ID.
+     *
+     * @param appId - The app ID
+     * @param itemId - The item ID
+     * @returns The data item
+     *
+     * @example
+     * ```typescript
+     * const bed = await userAppData.get('garden-planner', 'bed-1');
+     * // Returns: { id: 'bed-1', name: 'Vegetable Bed', plants: [...] }
+     * ```
+     */
+    function get(appId: string, itemId: string): Promise<any>;
+    /**
+     * Create or update a user data item.
+     * The item object must include an `id` field.
+     *
+     * @param appId - The app ID
+     * @param item - The data item (must include `id`)
+     * @returns The saved item
+     *
+     * @example
+     * ```typescript
+     * await userAppData.set('garden-planner', {
+     *   id: 'bed-1',
+     *   name: 'Vegetable Bed',
+     *   plants: ['tomatoes', 'peppers'],
+     *   location: { x: 10, y: 20 }
+     * });
+     * ```
+     */
+    function set(appId: string, item: any): Promise<any>;
+    /**
+     * Delete a user data item by ID.
+     *
+     * @param appId - The app ID
+     * @param itemId - The item ID to delete
+     *
+     * @example
+     * ```typescript
+     * await userAppData.remove('garden-planner', 'bed-1');
+     * ```
+     */
+    function remove(appId: string, itemId: string): Promise<void>;
+}
+/**
+ * Collection/Product-scoped app configuration.
+ * This is admin-managed configuration that applies to all users within the scope.
+ *
+ * @example
+ * ```typescript
+ * // Get collection-level app config
+ * const config = await appConfiguration.getConfig({
+ *   appId: 'warranty-portal',
+ *   collectionId: 'my-collection'
+ * });
+ *
+ * // Set product-level config (admin only)
+ * await appConfiguration.setConfig({
+ *   appId: 'warranty-portal',
+ *   collectionId: 'my-collection',
+ *   productId: 'product-123',
+ *   admin: true,
+ *   config: { warrantyPeriod: 24 }
+ * });
+ *
+ * // List product-level data items
+ * const items = await appConfiguration.getData({
+ *   appId: 'product-docs',
+ *   collectionId: 'my-collection',
+ *   productId: 'product-123'
+ * });
+ * ```
+ */
 export declare namespace appConfiguration {
+    /**
+     * Get app configuration for a collection/product scope.
+     *
+     * @param opts - Configuration options including appId and scope (collectionId, productId, etc.)
+     * @returns The configuration object
+     *
+     * @example
+     * ```typescript
+     * const config = await appConfiguration.getConfig({
+     *   appId: 'warranty-portal',
+     *   collectionId: 'my-collection'
+     * });
+     * ```
+     */
     function getConfig(opts: AppConfigOptions): Promise<any>;
+    /**
+     * Set app configuration for a collection/product scope.
+     * Requires admin authentication.
+     *
+     * @param opts - Configuration options including appId, scope, and config data
+     * @returns The saved configuration
+     *
+     * @example
+     * ```typescript
+     * await appConfiguration.setConfig({
+     *   appId: 'warranty-portal',
+     *   collectionId: 'my-collection',
+     *   admin: true,
+     *   config: { warrantyPeriod: 24, supportEmail: 'support@example.com' }
+     * });
+     * ```
+     */
     function setConfig(opts: AppConfigOptions): Promise<any>;
+    /**
+     * Delete app configuration for a collection/product scope.
+     * Requires admin authentication.
+     *
+     * @param opts - Configuration options including appId and scope
+     *
+     * @example
+     * ```typescript
+     * await appConfiguration.deleteConfig({
+     *   appId: 'warranty-portal',
+     *   collectionId: 'my-collection',
+     *   admin: true
+     * });
+     * ```
+     */
     function deleteConfig(opts: AppConfigOptions): Promise<void>;
+    /**
+     * Get all data items for an app within a scope.
+     *
+     * @param opts - Options including appId and scope (collectionId, productId, etc.)
+     * @returns Array of data items
+     *
+     * @example
+     * ```typescript
+     * const items = await appConfiguration.getData({
+     *   appId: 'product-docs',
+     *   collectionId: 'my-collection',
+     *   productId: 'product-123'
+     * });
+     * ```
+     */
     function getData(opts: AppConfigOptions): Promise<any[]>;
+    /**
+     * Get a single data item by ID within a scope.
+     *
+     * @param opts - Options including appId, scope, and itemId
+     * @returns The data item
+     *
+     * @example
+     * ```typescript
+     * const item = await appConfiguration.getDataItem({
+     *   appId: 'product-docs',
+     *   collectionId: 'my-collection',
+     *   productId: 'product-123',
+     *   itemId: 'manual-1'
+     * });
+     * ```
+     */
     function getDataItem(opts: AppConfigOptions): Promise<any>;
+    /**
+     * Set/create a data item within a scope.
+     * Requires admin authentication.
+     *
+     * @param opts - Options including appId, scope, and data
+     * @returns The saved data item
+     *
+     * @example
+     * ```typescript
+     * await appConfiguration.setDataItem({
+     *   appId: 'product-docs',
+     *   collectionId: 'my-collection',
+     *   productId: 'product-123',
+     *   admin: true,
+     *   data: { id: 'manual-1', title: 'User Manual', url: 'https://...' }
+     * });
+     * ```
+     */
     function setDataItem(opts: AppConfigOptions): Promise<any>;
+    /**
+     * Delete a data item by ID within a scope.
+     * Requires admin authentication.
+     *
+     * @param opts - Options including appId, scope, and itemId
+     *
+     * @example
+     * ```typescript
+     * await appConfiguration.deleteDataItem({
+     *   appId: 'product-docs',
+     *   collectionId: 'my-collection',
+     *   productId: 'product-123',
+     *   admin: true,
+     *   itemId: 'manual-1'
+     * });
+     * ```
+     */
     function deleteDataItem(opts: AppConfigOptions): Promise<void>;
     /**
      * Fetches ALL widget data (manifests + bundle files) for a collection in one call.

package/dist/api/appConfiguration.js

@@ -1,22 +1,6 @@
 // src/api/appConfiguration.ts
 import { request, post, del } from "../http";
 function buildAppPath(opts, type) {
-    if (opts.user) {
-        // /public/auth/app/:appId
-        let path = `/public/auth/app/${encodeURIComponent(opts.appId)}`;
-        if (type === "data")
-            path += "/data";
-        if (type === "dataItem" && opts.itemId)
-            path += `/data/${encodeURIComponent(opts.itemId)}`;
-        return path;
-    }
-    if (opts.userData) {
-        // /public/auth/app/:appId/data or /public/auth/app/:appId/data/:itemId
-        let path = `/public/auth/app/${encodeURIComponent(opts.appId)}/data`;
-        if (type === "dataItem" && opts.itemId)
-            path += `/${encodeURIComponent(opts.itemId)}`;
-        return path;
-    }
     const base = opts.admin ? "admin" : "public";
     let path = `/${base}`;
     if (opts.collectionId) {
@@ -40,33 +24,288 @@ function buildAppPath(opts, type) {
     }
     return path;
 }
+/**
+ * User-specific app data storage.
+ * This data is global per user+app and shared across all collections.
+ * Perfect for personal preferences, settings, and user-generated content.
+ *
+ * @example
+ * ```typescript
+ * // Store user's garden bed layout
+ * await userAppData.set('garden-planner', {
+ *   id: 'bed-1',
+ *   name: 'Vegetable Bed',
+ *   plants: ['tomatoes', 'peppers']
+ * });
+ *
+ * // Get all user's data for this app
+ * const beds = await userAppData.list('garden-planner');
+ *
+ * // Get specific item
+ * const bed = await userAppData.get('garden-planner', 'bed-1');
+ *
+ * // Remove item
+ * await userAppData.remove('garden-planner', 'bed-1');
+ * ```
+ */
+export var userAppData;
+(function (userAppData) {
+    /**
+     * Get user's config blob for an app.
+     * This is a single JSON object stored per user+app.
+     *
+     * @param appId - The app ID
+     * @returns The user's config object
+     *
+     * @example
+     * ```typescript
+     * const config = await userAppData.getConfig('allergy-tracker');
+     * // Returns: { allergies: ['peanuts'], notifications: true }
+     * ```
+     */
+    async function getConfig(appId) {
+        const path = `/public/auth/app/${encodeURIComponent(appId)}`;
+        return request(path);
+    }
+    userAppData.getConfig = getConfig;
+    /**
+     * Set user's config blob for an app.
+     *
+     * @param appId - The app ID
+     * @param config - The config object to store
+     *
+     * @example
+     * ```typescript
+     * await userAppData.setConfig('allergy-tracker', {
+     *   allergies: ['peanuts', 'shellfish'],
+     *   notifications: true
+     * });
+     * ```
+     */
+    async function setConfig(appId, config) {
+        const path = `/public/auth/app/${encodeURIComponent(appId)}`;
+        return post(path, config);
+    }
+    userAppData.setConfig = setConfig;
+    /**
+     * Delete user's config blob for an app.
+     *
+     * @param appId - The app ID
+     *
+     * @example
+     * ```typescript
+     * await userAppData.deleteConfig('allergy-tracker');
+     * ```
+     */
+    async function deleteConfig(appId) {
+        const path = `/public/auth/app/${encodeURIComponent(appId)}`;
+        return del(path);
+    }
+    userAppData.deleteConfig = deleteConfig;
+    /**
+     * List all user's data items for an app.
+     * Returns an array of objects, each with an `id` field.
+     *
+     * @param appId - The app ID
+     * @returns Array of data items
+     *
+     * @example
+     * ```typescript
+     * const beds = await userAppData.list('garden-planner');
+     * // Returns: [{ id: 'bed-1', name: 'Vegetables', ... }, { id: 'bed-2', ... }]
+     * ```
+     */
+    async function list(appId) {
+        const path = `/public/auth/app/${encodeURIComponent(appId)}/data`;
+        return request(path);
+    }
+    userAppData.list = list;
+    /**
+     * Get a specific user data item by ID.
+     *
+     * @param appId - The app ID
+     * @param itemId - The item ID
+     * @returns The data item
+     *
+     * @example
+     * ```typescript
+     * const bed = await userAppData.get('garden-planner', 'bed-1');
+     * // Returns: { id: 'bed-1', name: 'Vegetable Bed', plants: [...] }
+     * ```
+     */
+    async function get(appId, itemId) {
+        const path = `/public/auth/app/${encodeURIComponent(appId)}/data/${encodeURIComponent(itemId)}`;
+        return request(path);
+    }
+    userAppData.get = get;
+    /**
+     * Create or update a user data item.
+     * The item object must include an `id` field.
+     *
+     * @param appId - The app ID
+     * @param item - The data item (must include `id`)
+     * @returns The saved item
+     *
+     * @example
+     * ```typescript
+     * await userAppData.set('garden-planner', {
+     *   id: 'bed-1',
+     *   name: 'Vegetable Bed',
+     *   plants: ['tomatoes', 'peppers'],
+     *   location: { x: 10, y: 20 }
+     * });
+     * ```
+     */
+    async function set(appId, item) {
+        const path = `/public/auth/app/${encodeURIComponent(appId)}/data`;
+        return post(path, item);
+    }
+    userAppData.set = set;
+    /**
+     * Delete a user data item by ID.
+     *
+     * @param appId - The app ID
+     * @param itemId - The item ID to delete
+     *
+     * @example
+     * ```typescript
+     * await userAppData.remove('garden-planner', 'bed-1');
+     * ```
+     */
+    async function remove(appId, itemId) {
+        const path = `/public/auth/app/${encodeURIComponent(appId)}/data/${encodeURIComponent(itemId)}`;
+        return del(path);
+    }
+    userAppData.remove = remove;
+})(userAppData || (userAppData = {}));
+/**
+ * Collection/Product-scoped app configuration.
+ * This is admin-managed configuration that applies to all users within the scope.
+ *
+ * @example
+ * ```typescript
+ * // Get collection-level app config
+ * const config = await appConfiguration.getConfig({
+ *   appId: 'warranty-portal',
+ *   collectionId: 'my-collection'
+ * });
+ *
+ * // Set product-level config (admin only)
+ * await appConfiguration.setConfig({
+ *   appId: 'warranty-portal',
+ *   collectionId: 'my-collection',
+ *   productId: 'product-123',
+ *   admin: true,
+ *   config: { warrantyPeriod: 24 }
+ * });
+ *
+ * // List product-level data items
+ * const items = await appConfiguration.getData({
+ *   appId: 'product-docs',
+ *   collectionId: 'my-collection',
+ *   productId: 'product-123'
+ * });
+ * ```
+ */
 export var appConfiguration;
 (function (appConfiguration) {
-    // Get config (app, collection, product, variant, batch, user)
+    /**
+     * Get app configuration for a collection/product scope.
+     *
+     * @param opts - Configuration options including appId and scope (collectionId, productId, etc.)
+     * @returns The configuration object
+     *
+     * @example
+     * ```typescript
+     * const config = await appConfiguration.getConfig({
+     *   appId: 'warranty-portal',
+     *   collectionId: 'my-collection'
+     * });
+     * ```
+     */
     async function getConfig(opts) {
         const path = buildAppPath(opts, "config");
         return request(path);
     }
     appConfiguration.getConfig = getConfig;
-    // Set config (app, collection, product, variant, batch, user)
+    /**
+     * Set app configuration for a collection/product scope.
+     * Requires admin authentication.
+     *
+     * @param opts - Configuration options including appId, scope, and config data
+     * @returns The saved configuration
+     *
+     * @example
+     * ```typescript
+     * await appConfiguration.setConfig({
+     *   appId: 'warranty-portal',
+     *   collectionId: 'my-collection',
+     *   admin: true,
+     *   config: { warrantyPeriod: 24, supportEmail: 'support@example.com' }
+     * });
+     * ```
+     */
     async function setConfig(opts) {
         const path = buildAppPath(opts, "config");
         return post(path, opts.config);
     }
     appConfiguration.setConfig = setConfig;
-    // Delete config (user only)
+    /**
+     * Delete app configuration for a collection/product scope.
+     * Requires admin authentication.
+     *
+     * @param opts - Configuration options including appId and scope
+     *
+     * @example
+     * ```typescript
+     * await appConfiguration.deleteConfig({
+     *   appId: 'warranty-portal',
+     *   collectionId: 'my-collection',
+     *   admin: true
+     * });
+     * ```
+     */
     async function deleteConfig(opts) {
         const path = buildAppPath(opts, "config");
         return del(path);
     }
     appConfiguration.deleteConfig = deleteConfig;
-    // Get all data items (app, collection, product, variant, batch, userData)
+    /**
+     * Get all data items for an app within a scope.
+     *
+     * @param opts - Options including appId and scope (collectionId, productId, etc.)
+     * @returns Array of data items
+     *
+     * @example
+     * ```typescript
+     * const items = await appConfiguration.getData({
+     *   appId: 'product-docs',
+     *   collectionId: 'my-collection',
+     *   productId: 'product-123'
+     * });
+     * ```
+     */
     async function getData(opts) {
         const path = buildAppPath(opts, "data");
         return request(path);
     }
     appConfiguration.getData = getData;
-    // Get a single data item (app, collection, product, variant, batch, userData)
+    /**
+     * Get a single data item by ID within a scope.
+     *
+     * @param opts - Options including appId, scope, and itemId
+     * @returns The data item
+     *
+     * @example
+     * ```typescript
+     * const item = await appConfiguration.getDataItem({
+     *   appId: 'product-docs',
+     *   collectionId: 'my-collection',
+     *   productId: 'product-123',
+     *   itemId: 'manual-1'
+     * });
+     * ```
+     */
     async function getDataItem(opts) {
         if (!opts.itemId)
             throw new Error("itemId is required for getDataItem");
@@ -74,13 +313,46 @@ export var appConfiguration;
         return request(path);
     }
     appConfiguration.getDataItem = getDataItem;
-    // Set a data item (app, collection, product, variant, batch, userData)
+    /**
+     * Set/create a data item within a scope.
+     * Requires admin authentication.
+     *
+     * @param opts - Options including appId, scope, and data
+     * @returns The saved data item
+     *
+     * @example
+     * ```typescript
+     * await appConfiguration.setDataItem({
+     *   appId: 'product-docs',
+     *   collectionId: 'my-collection',
+     *   productId: 'product-123',
+     *   admin: true,
+     *   data: { id: 'manual-1', title: 'User Manual', url: 'https://...' }
+     * });
+     * ```
+     */
     async function setDataItem(opts) {
         const path = buildAppPath(opts, "data");
         return post(path, opts.data);
     }
     appConfiguration.setDataItem = setDataItem;
-    // Delete a data item (app, collection, product, variant, batch, userData)
+    /**
+     * Delete a data item by ID within a scope.
+     * Requires admin authentication.
+     *
+     * @param opts - Options including appId, scope, and itemId
+     *
+     * @example
+     * ```typescript
+     * await appConfiguration.deleteDataItem({
+     *   appId: 'product-docs',
+     *   collectionId: 'my-collection',
+     *   productId: 'product-123',
+     *   admin: true,
+     *   itemId: 'manual-1'
+     * });
+     * ```
+     */
     async function deleteDataItem(opts) {
         if (!opts.itemId)
             throw new Error("itemId is required for deleteDataItem");

package/dist/api/index.d.ts

@@ -1,7 +1,7 @@
 export { collection } from "./collection";
 export { product } from "./product";
 export { proof } from "./proof";
-export { appConfiguration } from "./appConfiguration";
+export { appConfiguration, userAppData } from "./appConfiguration";
 export { asset } from "./asset";
 export { attestation } from "./attestation";
 export { auth } from "./auth";

package/dist/api/index.js

@@ -3,7 +3,7 @@
 export { collection } from "./collection";
 export { product } from "./product";
 export { proof } from "./proof";
-export { appConfiguration } from "./appConfiguration";
+export { appConfiguration, userAppData } from "./appConfiguration";
 export { asset } from "./asset";
 export { attestation } from "./attestation";
 export { auth } from "./auth";