@proveanything/smartlinks 1.0.13 → 1.0.16

package/README.md

@@ -22,11 +22,12 @@ import {
 } from "@proveanything/smartlinks";
 
 async function main() {
-  // Initialize once (provide base URL and optional API key/bearer token)
+  // Initialize once (provide base URL and optional API key, bearer token, or proxyMode)
   initializeApi({
     baseURL: "https://smartlinks.app/api/v1",
     apiKey: "YOUR_API_KEY_HERE",       // optional
     bearerToken: "YOUR_BEARER_TOKEN",  // optional
+    proxyMode: false                   // optional, set true if running in iframe via parent proxy
   });
 
   try {
@@ -58,168 +59,29 @@ main();
 ### Initialization
 
 ```ts
-initializeApi(options: { baseURL: string; apiKey?: string; bearerToken?: string }): void
+initializeApi(options: { baseURL: string; apiKey?: string; bearerToken?: string; proxyMode?: boolean }): void
 ```
 
 - **Parameters:**
   - `baseURL` (`string`, required): The root URL of the Smartlinks API, e.g. `https://smartlinks.app/api/v1`.
   - `apiKey`  (`string`, optional): Your API key for the `X-API-Key` header.
-  - `bearerToken` (`string`, optional): Your Bearer token for the `AUTHORIZATION` header.
+  - `bearerToken` (`string`, optional): Your Bearer token for the `Authorization` header.
+  - `proxyMode` (`boolean`, optional): Set to `true` if running in an iframe and using a parent proxy for requests.
 
 All subsequent calls to the API functions will use these settings.
 
 ---
 
-### Namespace: `collection`
+### Namespaced Modules
 
-#### `collection.get(collectionId: string): Promise<CollectionResponse>`
+Each namespace provides a `get` method for fetching data:
 
-Fetches a single collection by its ID.
+- **collection.get(collectionId: string): Promise<Collection>**
+- **product.get(collectionId: string, productId: string): Promise<Product>**
+- **proof.get(collectionId: string, proofId: string): Promise<Proof>**
+- **appConfiguration.get(collectionId: string, appId: string): Promise<AppConfiguration>**
 
-- **Parameters:**
-  - `collectionId` (`string`, required): The unique identifier of the collection to fetch.
-- **Returns:**  
-  A `Promise` that resolves to a `CollectionResponse` object:
-
-  ```ts
-  export interface CollectionResponse {
-    id: string;
-    name: string;
-    title: string;
-    logoImage: string;
-  }
-  ```
-
-- **Example:**
-  ```ts
-  const coll = await collection.get("abc123");
-  console.log("Fetched collection:", coll.title);
-  ```
-
----
-
-### Namespace: `product`
-
-#### `product.get(collectionId: string, productId: string): Promise<ProductResponse>`
-
-Fetches a single product item within a collection.
-
-- **Parameters:**
-  - `collectionId` (`string`, required): The parent collection’s ID.
-  - `productId`    (`string`, required): The product item’s ID.
-- **Returns:**  
-  A `Promise` that resolves to a `ProductResponse` object:
-
-  ```ts
-  export interface ProductResponse {
-    id: string;
-    name: string;
-    description: string;
-    heroImage: string;
-  }
-  ```
-
-- **Example:**
-  ```ts
-  const prod = await product.get("abc123", "prod789");
-  console.log("Fetched product:", prod.name);
-  ```
-
----
-
-### Namespace: `proof`
-
-#### `proof.get(collectionId: string, proofId: string): Promise<ProofResponse>`
-
-Fetches a single proof by collection ID and proof ID.
-
-- **Parameters:**
-  - `collectionId` (`string`, required): The parent collection’s ID.
-  - `proofId`      (`string`, required): The proof’s ID.
-- **Returns:**  
-  A `Promise` that resolves to a `ProofResponse` object:
-
-  ```ts
-  export interface ProofResponse {
-    collectionId: string;
-    createdAt: string;
-    id: string;
-    productId: string;
-    tokenId: string;
-    userId: string;
-    values: Record<string, any>;
-  }
-  ```
-
-- **Example:**
-  ```ts
-  const prf = await proof.get("abc123", "proof456");
-  console.log("Fetched proof:", prf.id);
-  ```
-
----
-
-### Namespace: `appConfiguration`
-
-#### `appConfiguration.get(collectionId: string, appId: string): Promise<AppConfigurationResponse>`
-
-Fetches a single app configuration by collection ID and app ID.
-
-- **Parameters:**
-  - `collectionId` (`string`, required): The parent collection’s ID.
-  - `appId`        (`string`, required): The app configuration’s ID.
-- **Returns:**  
-  A `Promise` that resolves to an `AppConfigurationResponse` object:
-
-  ```ts
-  export interface AppConfigurationResponse {
-    id: string;
-    name: string;
-    settings?: Record<string, any>;
-  }
-  ```
-
-- **Example:**
-  ```ts
-  const cfg = await appConfiguration.get("abc123", "app789");
-  console.log("Fetched app configuration:", cfg.name);
-  ```
-
----
-
-## Error Handling
-
-All methods throw an `Error` when the server responds with a non-2xx status. The thrown error message will include the numeric error code and message from the API. Example:
-
-```ts
-import { product } from "@proveanything/smartlinks";
-
-async function fetchProduct() {
-  try {
-    await product.get("abc123", "invalidProdId");
-  } catch (err) {
-    // err.message might be: "Error 404: Not Found"
-    console.error("Request failed:", err);
-  }
-}
-
-fetchProduct();
-```
-
----
-
-## Types
-
-You can import any of the response interfaces directly:
-
-```ts
-import {
-  CollectionResponse,
-  ProductResponse,
-  ProofResponse,
-  AppConfigurationResponse,
-} from "@proveanything/smartlinks/types";
-```
+All methods return a Promise resolving to the corresponding object, or throw an `Error` on failure.
 
 ---
 

package/build-docs.ts

@@ -0,0 +1,28 @@
+import { execSync } from "child_process"
+import { readdirSync, readFileSync, writeFileSync, existsSync, mkdirSync } from "fs"
+import { join, extname } from "path"
+
+// Run TypeDoc to generate markdown docs in temp-docs
+execSync("npx typedoc --out temp-docs --plugin typedoc-plugin-markdown --entryPoints src/index.ts --excludePrivate --excludeInternal --hideBreadcrumbs --hidePageTitle", { stdio: "inherit" })
+
+const tempDocsDir = join(__dirname, "..", "temp-docs")
+const docsDir = join(__dirname, "..", "docs")
+const outPath = join(docsDir, "README.md")
+
+if (!existsSync(docsDir)) mkdirSync(docsDir)
+
+const files = readdirSync(tempDocsDir)
+  .filter(f => extname(f) === ".md")
+  .sort((a, b) => a === "modules.md" ? -1 : a.localeCompare(b)) // modules.md first
+
+let content = "# Smartlinks SDK Documentation\n\n"
+for (const file of files) {
+  const fileContent = readFileSync(join(tempDocsDir, file), "utf-8")
+  // Remove redundant titles (except for the first file)
+  content += file === "modules.md"
+    ? fileContent + "\n\n"
+    : fileContent.replace(/^# .*\n/, "") + "\n\n"
+}
+
+writeFileSync(outPath, content)
+console.log("Documentation built at docs/README.md")

package/dist/api/appConfiguration.d.ts

@@ -1,11 +1,22 @@
-import { AppConfigurationResponse } from "../types/appConfiguration";
+export type AppConfigOptions = {
+    appId: string;
+    collectionId?: string;
+    productId?: string;
+    variantId?: string;
+    batchId?: string;
+    itemId?: string;
+    user?: boolean;
+    userData?: boolean;
+    admin?: boolean;
+    config?: any;
+    data?: any;
+};
 export declare namespace appConfiguration {
-    /**
-     * Retrieves a single App Configuration by Collection ID and App ID.
-     * @param collectionId – Identifier of the parent collection
-     * @param appId        – Identifier of the app configuration
-     * @returns Promise resolving to an AppConfigurationResponse object
-     * @throws ErrorResponse if the request fails
-     */
-    function get(collectionId: string, appId: string): Promise<AppConfigurationResponse>;
+    function getConfig(opts: AppConfigOptions): Promise<any>;
+    function setConfig(opts: AppConfigOptions): Promise<any>;
+    function deleteConfig(opts: AppConfigOptions): Promise<void>;
+    function getData(opts: AppConfigOptions): Promise<any[]>;
+    function getDataItem(opts: AppConfigOptions): Promise<any>;
+    function setDataItem(opts: AppConfigOptions): Promise<any>;
+    function deleteDataItem(opts: AppConfigOptions): Promise<void>;
 }

package/dist/api/appConfiguration.js

@@ -1,17 +1,91 @@
 // src/api/appConfiguration.ts
-import { request } from "../http";
+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) {
+        path += `/collection/${encodeURIComponent(opts.collectionId)}`;
+        if (opts.productId) {
+            path += `/product/${encodeURIComponent(opts.productId)}`;
+            if (opts.variantId) {
+                path += `/variant/${encodeURIComponent(opts.variantId)}`;
+            }
+            else if (opts.batchId) {
+                path += `/batch/${encodeURIComponent(opts.batchId)}`;
+            }
+        }
+    }
+    path += `/app/${encodeURIComponent(opts.appId)}`;
+    if (type === "data" || type === "dataItem") {
+        path += "/data";
+        if (type === "dataItem" && opts.itemId) {
+            path += `/${encodeURIComponent(opts.itemId)}`;
+        }
+    }
+    return path;
+}
 export var appConfiguration;
 (function (appConfiguration) {
-    /**
-     * Retrieves a single App Configuration by Collection ID and App ID.
-     * @param collectionId – Identifier of the parent collection
-     * @param appId        – Identifier of the app configuration
-     * @returns Promise resolving to an AppConfigurationResponse object
-     * @throws ErrorResponse if the request fails
-     */
-    async function get(collectionId, appId) {
-        const path = `/public/collection/${encodeURIComponent(collectionId)}/app/${encodeURIComponent(appId)}`;
+    // Get config (app, collection, product, variant, batch, user)
+    async function getConfig(opts) {
+        const path = buildAppPath(opts, "config");
+        return request(path);
+    }
+    appConfiguration.getConfig = getConfig;
+    // Set config (app, collection, product, variant, batch, user)
+    async function setConfig(opts) {
+        const path = buildAppPath(opts, "config");
+        return post(path, opts.config);
+    }
+    appConfiguration.setConfig = setConfig;
+    // Delete config (user only)
+    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)
+    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)
+    async function getDataItem(opts) {
+        if (!opts.itemId)
+            throw new Error("itemId is required for getDataItem");
+        const path = buildAppPath(opts, "dataItem");
         return request(path);
     }
-    appConfiguration.get = get;
+    appConfiguration.getDataItem = getDataItem;
+    // Set a data item (app, collection, product, variant, batch, userData)
+    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)
+    async function deleteDataItem(opts) {
+        if (!opts.itemId)
+            throw new Error("itemId is required for deleteDataItem");
+        const path = buildAppPath(opts, "dataItem");
+        return del(path);
+    }
+    appConfiguration.deleteDataItem = deleteDataItem;
 })(appConfiguration || (appConfiguration = {}));

package/dist/api/auth.d.ts

@@ -1,18 +1,18 @@
-type LoginResponse = {
+export type LoginResponse = {
     id: string;
     name: string;
     email: string;
     bearerToken: string;
     account: Record<string, any>;
 };
-type VerifyTokenResponse = {
+export type VerifyTokenResponse = {
     valid: boolean;
     id?: string;
     name?: string;
     email?: string;
     account?: Record<string, any>;
 };
-type AccountInfoResponse = {
+export type AccountInfoResponse = {
     user: Record<string, any>;
     owner: Record<string, any>;
     account: Record<string, any>;
@@ -39,4 +39,3 @@ export declare namespace auth {
      */
     function getAccount(): Promise<AccountInfoResponse>;
 }
-export {};

package/dist/api/auth.js

@@ -1,4 +1,4 @@
-import { post, setBearerToken, getApiHeaders } from "../http";
+import { post, request, setBearerToken, getApiHeaders } from "../http";
 export var auth;
 (function (auth) {
     /**
@@ -40,7 +40,7 @@ export var auth;
      * Returns user, owner, account, and location objects.
      */
     async function getAccount() {
-        return post("/public/auth/account", {});
+        return request("/public/auth/account");
     }
     auth.getAccount = getAccount;
 })(auth || (auth = {}));

package/dist/build-docs.js

@@ -0,0 +1,26 @@
+"use strict";
+exports.__esModule = true;
+var child_process_1 = require("child_process");
+var fs_1 = require("fs");
+var path_1 = require("path");
+// Run TypeDoc to generate markdown docs in temp-docs
+(0, child_process_1.execSync)("npx typedoc --out temp-docs --plugin typedoc-plugin-markdown --entryPoints src/index.ts --excludePrivate --excludeInternal --hideBreadcrumbs --hidePageTitle", { stdio: "inherit" });
+var tempDocsDir = (0, path_1.join)(__dirname, "..", "temp-docs");
+var docsDir = (0, path_1.join)(__dirname, "..", "docs");
+var outPath = (0, path_1.join)(docsDir, "README.md");
+if (!(0, fs_1.existsSync)(docsDir))
+    (0, fs_1.mkdirSync)(docsDir);
+var files = (0, fs_1.readdirSync)(tempDocsDir)
+    .filter(function (f) { return (0, path_1.extname)(f) === ".md"; })
+    .sort(function (a, b) { return a === "modules.md" ? -1 : a.localeCompare(b); }); // modules.md first
+var content = "# Smartlinks SDK Documentation\n\n";
+for (var _i = 0, files_1 = files; _i < files_1.length; _i++) {
+    var file = files_1[_i];
+    var fileContent = (0, fs_1.readFileSync)((0, path_1.join)(tempDocsDir, file), "utf-8");
+    // Remove redundant titles (except for the first file)
+    content += file === "modules.md"
+        ? fileContent + "\n\n"
+        : fileContent.replace(/^# .*\n/, "") + "\n\n";
+}
+(0, fs_1.writeFileSync)(outPath, content);
+console.log("Documentation built at docs/README.md");

package/dist/http.d.ts

@@ -1,9 +1,11 @@
 /**
  * Call this once (e.g. at app startup) to configure baseURL/auth.
  *
- * @param options.baseURL - The root URL of the Smartlinks API (e.g. "https://smartlinks.app/api/v1")
- * @param options.apiKey - (Optional) API key for X-API-Key header
- * @param options.bearerToken - (Optional) Bearer token for AUTHORIZATION header
+ * @param options - Configuration options
+ * @property {string} options.baseURL - The root URL of the Smartlinks API (e.g. "https://smartlinks.app/api/v1")
+ * @property {string} [options.apiKey] - (Optional) API key for X-API-Key header
+ * @property {string} [options.bearerToken] - (Optional) Bearer token for AUTHORIZATION header
+ * @property {boolean} [options.proxyMode] - (Optional) Tells the API that it is running in an iframe via parent proxy
  */
 export declare function initializeApi(options: {
     baseURL: string;

package/dist/http.js

@@ -9,9 +9,11 @@ let proxyMode = false;
 /**
  * Call this once (e.g. at app startup) to configure baseURL/auth.
  *
- * @param options.baseURL - The root URL of the Smartlinks API (e.g. "https://smartlinks.app/api/v1")
- * @param options.apiKey - (Optional) API key for X-API-Key header
- * @param options.bearerToken - (Optional) Bearer token for AUTHORIZATION header
+ * @param options - Configuration options
+ * @property {string} options.baseURL - The root URL of the Smartlinks API (e.g. "https://smartlinks.app/api/v1")
+ * @property {string} [options.apiKey] - (Optional) API key for X-API-Key header
+ * @property {string} [options.bearerToken] - (Optional) Bearer token for AUTHORIZATION header
+ * @property {boolean} [options.proxyMode] - (Optional) Tells the API that it is running in an iframe via parent proxy
  */
 export function initializeApi(options) {
     baseURL = options.baseURL.replace(/\/+\$/, ""); // trim trailing slash

package/dist/index.d.ts

@@ -1,3 +1,6 @@
 export { initializeApi, request } from "./http";
 export * from "./api";
 export * from "./types";
+export type { LoginResponse, VerifyTokenResponse, AccountInfoResponse, } from "./api/auth";
+export type { AttestationResponse, AttestationCreateRequest, AttestationUpdateRequest, } from "./types/attestation";
+export type { AppConfigOptions } from "./api/appConfiguration";