@proveanything/smartlinks 1.0.0

package/README.md

@@ -0,0 +1,184 @@
+# @smartlinks/sdk
+
+An official JavaScript/TypeScript client SDK for the Smartlinks API. This package provides a simple wrapper around the Smartlinks REST endpoints, allowing you to fetch Collection, Product, and App Configuration data in both browser and Node.js environments.
+
+## Installation
+
+```bash
+npm install @smartlinks/sdk
+# or
+yarn add @smartlinks/sdk
+```
+
+## Quickstart
+
+```ts
+import { ApiClient, CollectionResponse, ProductResponse } from "@smartlinks/sdk";
+
+async function main() {
+  // Instantiate the client (no apiKey needed for public endpoints, but shown here for reference)
+  const client = new ApiClient("https://smartlinks.app/api/v1", "YOUR_API_KEY_HERE");
+
+  try {
+    // Fetch a collection by ID
+    const collection: CollectionResponse = await client.getCollection("abc123");
+    console.log("Collection:", collection);
+
+    // Fetch a product item by collection ID & product ID
+    const product: ProductResponse = await client.getProductItem("abc123", "prod789");
+    console.log("Product Item:", product);
+  } catch (err) {
+    console.error("Error fetching data:", err);
+  }
+}
+
+main();
+```
+
+## API Reference
+
+### Class: `ApiClient`
+
+```ts
+constructor(baseURL: string, apiKey?: string)
+```
+
+- **Parameters:**
+  - `baseURL` (`string`, required): The root URL of the Smartlinks API, e.g. `https://smartlinks.app/api/v1`.  
+  - `apiKey` (`string`, optional): Your Bearer token. If omitted, requests will be sent without an `Authorization` header.
+
+---
+
+#### `getCollection(collectionId: string): Promise<CollectionResponse>`
+
+Fetches a single collection by its ID.
+
+- **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 client = new ApiClient("https://smartlinks.app/api/v1", "YOUR_API_KEY");
+  const collection = await client.getCollection("abc123");
+  console.log("Fetched collection:", collection);
+  ```
+
+---
+
+#### `getProductItem(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 client = new ApiClient("https://smartlinks.app/api/v1", "YOUR_API_KEY");
+  const product = await client.getProductItem("abc123", "prod789");
+  console.log("Fetched product:", product);
+  ```
+
+---
+
+#### `getAppConfiguration(collectionId: string, appId: string): Promise<AppConfigurationResponse>`
+
+Fetches a single app configuration within a collection.
+
+- **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 client = new ApiClient("https://smartlinks.app/api/v1", "YOUR_API_KEY");
+  const config = await client.getAppConfiguration("abc123", "app456");
+  console.log("Fetched app configuration:", config);
+  ```
+
+---
+
+## Authentication
+
+All endpoints require a Bearer token passed in the `AUTHORIZATION` header. When instantiating `ApiClient`, optionally supply your token:
+
+```ts
+import { ApiClient } from "@smartlinks/sdk";
+
+const apiKey = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
+const client = new ApiClient("https://smartlinks.app/api/v1", apiKey);
+```
+
+If `apiKey` is omitted, requests will be sent without an `Authorization` header, which may cause a `401 Unauthorized` for protected endpoints.
+
+## Error Handling
+
+All methods throw an `Error` when the server responds with a non-2xx status. The thrown error message includes the numeric error code and message from the API. Example:
+
+```ts
+import { ApiClient } from "@smartlinks/sdk";
+
+async function fetchData() {
+  const client = new ApiClient("https://smartlinks.app/api/v1", "INVALID_KEY");
+
+  try {
+    await client.getCollection("nonexistent");
+  } catch (err) {
+    // err.message might be: "Error 401: Unauthorized" or "Error 404: Not Found"
+    console.error("Request failed:", err);
+  }
+}
+
+fetchData();
+```
+
+## Examples
+
+See the **examples/** folder for complete, runnable samples:
+
+- [`examples/node-demo.ts`](examples/node-demo.ts)  
+- [`examples/browser-demo.html`](examples/browser-demo.html)  
+- [`examples/react-demo.tsx`](examples/react-demo.tsx)  
+
+## Changelog
+
+### 1.0.0
+
+- Initial release:  
+  - `ApiClient` class with `getCollection`, `getProductItem`, and `getAppConfiguration` methods.  
+  - Full TypeScript typings and JSDoc.  
+  - Browser/Node fetch support.  
+  - Error handling via thrown `Error` objects.

package/dist/index.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Represents a Collection object.
+ */
+export interface CollectionResponse {
+    /** Unique identifier for the collection */
+    id: string;
+    /** Machine‐readable name of the collection */
+    name: string;
+    /** Human‐readable title of the collection */
+    title: string;
+    /** URL to the collection’s logo image */
+    logoImage: string;
+}
+/**
+ * Represents a Product Item object.
+ */
+export interface ProductResponse {
+    /** Unique identifier for the product */
+    id: string;
+    /** Name of the product */
+    name: string;
+    /** Detailed description of the product */
+    description: string;
+    /** URL to the product’s hero image */
+    heroImage: string;
+}
+/**
+ * Represents an App Configuration object.
+ */
+export interface AppConfigurationResponse {
+    /** Unique identifier for the app configuration */
+    id: string;
+    /** Name of the app configuration */
+    name: string;
+    /** Key‐value pairs representing configuration settings */
+    settings?: Record<string, any>;
+}
+/**
+ * Represents a standardized error response.
+ */
+export interface ErrorResponse {
+    /** Numeric error code */
+    code: number;
+    /** Human‐readable error message */
+    message: string;
+}
+/**
+ * ApiClient for the Smartlinks API.
+ * Supports both browser (native fetch) and Node (using cross-fetch).
+ */
+export declare class ApiClient {
+    private baseURL;
+    private apiKey?;
+    private bearerToken?;
+    /**
+     * Creates an instance of ApiClient.
+     * @param baseURL - The base URL of the Smartlinks API (e.g., https://smartlinks.app/api/v1)
+     * @param apiKey - (Optional) API key for X-API-Key header
+     * @param bearerToken - (Optional) Bearer token for AUTHORIZATION header
+     *
+     * @example
+     * // With both API key and bearer token
+     * const client = new ApiClient(
+     *   'https://smartlinks.app/api/v1',
+     *   'your-api-key',
+     *   'your-bearer-token'
+     * );
+     *
+     * // With only API key
+     * const client = new ApiClient(
+     *   'https://smartlinks.app/api/v1',
+     *   'your-api-key'
+     * );
+     *
+     * // With only bearer token
+     * const client = new ApiClient(
+     *   'https://smartlinks.app/api/v1',
+     *   undefined,
+     *   'your-bearer-token'
+     * );
+     */
+    constructor(baseURL: string, apiKey?: string, bearerToken?: string);
+    /**
+     * Retrieves a single Collection by its ID.
+     * @param collectionId - Identifier of the collection
+     * @returns Promise resolving to a CollectionResponse object
+     * @throws ErrorResponse if the request fails
+     */
+    getCollection(collectionId: string): Promise<CollectionResponse>;
+    /**
+     * Retrieves a single Product Item by Collection ID and Product ID.
+     * @param collectionId - Identifier of the parent collection
+     * @param productId - Identifier of the product item
+     * @returns Promise resolving to a ProductResponse object
+     * @throws ErrorResponse if the request fails
+     */
+    getProductItem(collectionId: string, productId: string): Promise<ProductResponse>;
+    /**
+     * 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
+     */
+    getAppConfiguration(collectionId: string, appId: string): Promise<AppConfigurationResponse>;
+    /**
+     * Internal helper to perform a GET request and parse JSON.
+     * @param path - The path (relative to baseURL) to request
+     * @returns Promise resolving to the parsed JSON of type T
+     * @throws Error if network error or a non-2xx response is returned
+     */
+    private request;
+}

package/dist/index.js

@@ -0,0 +1,105 @@
+import fetch from 'cross-fetch';
+///////////////////////////
+// ApiClient Class
+///////////////////////////
+/**
+ * ApiClient for the Smartlinks API.
+ * Supports both browser (native fetch) and Node (using cross-fetch).
+ */
+export class ApiClient {
+    /**
+     * Creates an instance of ApiClient.
+     * @param baseURL - The base URL of the Smartlinks API (e.g., https://smartlinks.app/api/v1)
+     * @param apiKey - (Optional) API key for X-API-Key header
+     * @param bearerToken - (Optional) Bearer token for AUTHORIZATION header
+     *
+     * @example
+     * // With both API key and bearer token
+     * const client = new ApiClient(
+     *   'https://smartlinks.app/api/v1',
+     *   'your-api-key',
+     *   'your-bearer-token'
+     * );
+     *
+     * // With only API key
+     * const client = new ApiClient(
+     *   'https://smartlinks.app/api/v1',
+     *   'your-api-key'
+     * );
+     *
+     * // With only bearer token
+     * const client = new ApiClient(
+     *   'https://smartlinks.app/api/v1',
+     *   undefined,
+     *   'your-bearer-token'
+     * );
+     */
+    constructor(baseURL, apiKey, bearerToken) {
+        this.baseURL = baseURL.replace(/\/+$/, ''); // Trim trailing slash
+        this.apiKey = apiKey;
+        this.bearerToken = bearerToken;
+    }
+    /**
+     * Retrieves a single Collection by its ID.
+     * @param collectionId - Identifier of the collection
+     * @returns Promise resolving to a CollectionResponse object
+     * @throws ErrorResponse if the request fails
+     */
+    async getCollection(collectionId) {
+        const path = `/public/collection/${encodeURIComponent(collectionId)}`;
+        return this.request(path);
+    }
+    /**
+     * Retrieves a single Product Item by Collection ID and Product ID.
+     * @param collectionId - Identifier of the parent collection
+     * @param productId - Identifier of the product item
+     * @returns Promise resolving to a ProductResponse object
+     * @throws ErrorResponse if the request fails
+     */
+    async getProductItem(collectionId, productId) {
+        const path = `/public/collection/${encodeURIComponent(collectionId)}/product/${encodeURIComponent(productId)}`;
+        return this.request(path);
+    }
+    /**
+     * 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 getAppConfiguration(collectionId, appId) {
+        const path = `/public/collection/${encodeURIComponent(collectionId)}/app/${encodeURIComponent(appId)}`;
+        return this.request(path);
+    }
+    /**
+     * Internal helper to perform a GET request and parse JSON.
+     * @param path - The path (relative to baseURL) to request
+     * @returns Promise resolving to the parsed JSON of type T
+     * @throws Error if network error or a non-2xx response is returned
+     */
+    async request(path) {
+        const url = `${this.baseURL}${path}`;
+        const headers = {
+            'Content-Type': 'application/json',
+        };
+        if (this.apiKey) {
+            headers['X-API-Key'] = this.apiKey;
+        }
+        if (this.bearerToken) {
+            headers['AUTHORIZATION'] = `Bearer ${this.bearerToken}`;
+        }
+        const response = await fetch(url, { method: 'GET', headers });
+        if (!response.ok) {
+            // Attempt to parse error body; if it fails, throw generic
+            let errorBody;
+            try {
+                errorBody = (await response.json());
+            }
+            catch (_a) {
+                throw new Error(`Request failed with status ${response.status}`);
+            }
+            throw new Error(`Error ${errorBody.code}: ${errorBody.message}`);
+        }
+        return (await response.json());
+    }
+}

package/examples/browser-demo.html

@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8" />
+  <title>Smartlinks SDK Browser Demo</title>
+</head>
+<body>
+  <h1>Smartlinks SDK Browser Demo</h1>
+  <pre id="output"></pre>
+  <script type="module">
+    import { ApiClient } from '../dist/index.js';
+
+    async function run() {
+      // You can provide either or both of these values:
+      const apiKey = 'YOUR_API_KEY'; // sent as X-API-Key header (optional)
+      const bearerToken = 'YOUR_BEARER_TOKEN'; // sent as AUTHORIZATION: Bearer ... (optional)
+
+      // Example: with both headers
+      const client = new ApiClient('https://smartlinks.app/api/v1', apiKey, bearerToken);
+
+      try {
+        const collection = await client.getCollection('abc123');
+        const product = await client.getProductItem('abc123', 'prod789');
+        document.getElementById('output').textContent = JSON.stringify({ collection, product }, null, 2);
+      } catch (err) {
+        document.getElementById('output').textContent = 'Error: ' + err.message;
+      }
+    }
+    run();
+  </script>
+</body>
+</html>

package/examples/node-demo.ts

@@ -0,0 +1,22 @@
+import { ApiClient, CollectionResponse, ProductResponse } from "../src/index";
+
+async function main() {
+  // You can provide either or both of these values:
+  const apiKey = "YOUR_API_KEY"; // sent as X-API-Key header (optional)
+  const bearerToken = "YOUR_BEARER_TOKEN"; // sent as AUTHORIZATION: Bearer ... (optional)
+
+  // Example: with both headers
+  const client = new ApiClient("https://smartlinks.app/api/v1", apiKey, bearerToken);
+
+  try {
+    const collection: CollectionResponse = await client.getCollection("abc123");
+    console.log("Collection:", collection);
+
+    const product: ProductResponse = await client.getProductItem("abc123", "prod789");
+    console.log("Product Item:", product);
+  } catch (err) {
+    console.error("Error fetching data:", err);
+  }
+}
+
+main();

package/examples/react-demo.tsx

@@ -0,0 +1,44 @@
+import React, { useEffect, useState } from 'react';
+import { ApiClient, CollectionResponse, ProductResponse } from '@smartlinks/sdk';
+
+// You can provide either or both of these values:
+const apiKey = 'YOUR_API_KEY'; // sent as X-API-Key header (optional)
+const bearerToken = 'YOUR_BEARER_TOKEN'; // sent as AUTHORIZATION: Bearer ... (optional)
+
+// Example: with both headers
+const client = new ApiClient('https://smartlinks.app/api/v1', apiKey, bearerToken);
+
+const ReactDemo: React.FC = () => {
+  const [collection, setCollection] = useState<CollectionResponse | null>(null);
+  const [product, setProduct] = useState<ProductResponse | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    async function fetchData() {
+      try {
+        const col = await client.getCollection('abc123');
+        const prod = await client.getProductItem('abc123', 'prod789');
+        setCollection(col);
+        setProduct(prod);
+      } catch (err) {
+        setError((err as Error).message);
+      }
+    }
+    fetchData();
+  }, []);
+
+  if (error) return <div>Error: {error}</div>;
+  if (!collection || !product) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <h1>{collection.title}</h1>
+      <img src={collection.logoImage} alt={collection.title} width="100" />
+      <h2>{product.name}</h2>
+      <img src={product.heroImage} alt={product.name} width="100" />
+      <p>{product.description}</p>
+    </div>
+  );
+};
+
+export default ReactDemo;

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@proveanything/smartlinks",
+  "version": "1.0.0",
+  "description": "Official JavaScript/TypeScript SDK for the Smartlinks API",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "author": "Glenn Shoosmith",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "cross-fetch": "^3.1.5"
+  },
+  "devDependencies": {
+    "typescript": "^4.9.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,171 @@
+import fetch from 'cross-fetch';
+
+///////////////////////////
+// Schema Interfaces
+///////////////////////////
+
+/**
+ * Represents a Collection object.
+ */
+export interface CollectionResponse {
+  /** Unique identifier for the collection */
+  id: string;
+  /** Machine‐readable name of the collection */
+  name: string;
+  /** Human‐readable title of the collection */
+  title: string;
+  /** URL to the collection’s logo image */
+  logoImage: string;
+}
+
+/**
+ * Represents a Product Item object.
+ */
+export interface ProductResponse {
+  /** Unique identifier for the product */
+  id: string;
+  /** Name of the product */
+  name: string;
+  /** Detailed description of the product */
+  description: string;
+  /** URL to the product’s hero image */
+  heroImage: string;
+}
+
+/**
+ * Represents an App Configuration object.
+ */
+export interface AppConfigurationResponse {
+  /** Unique identifier for the app configuration */
+  id: string;
+  /** Name of the app configuration */
+  name: string;
+  /** Key‐value pairs representing configuration settings */
+  settings?: Record<string, any>;
+}
+
+/**
+ * Represents a standardized error response.
+ */
+export interface ErrorResponse {
+  /** Numeric error code */
+  code: number;
+  /** Human‐readable error message */
+  message: string;
+}
+
+///////////////////////////
+// ApiClient Class
+///////////////////////////
+
+/**
+ * ApiClient for the Smartlinks API.
+ * Supports both browser (native fetch) and Node (using cross-fetch).
+ */
+export class ApiClient {
+  private baseURL: string;
+  private apiKey?: string;
+  private bearerToken?: string;
+
+  /**
+   * Creates an instance of ApiClient.
+   * @param baseURL - The base URL of the Smartlinks API (e.g., https://smartlinks.app/api/v1)
+   * @param apiKey - (Optional) API key for X-API-Key header
+   * @param bearerToken - (Optional) Bearer token for AUTHORIZATION header
+   *
+   * @example
+   * // With both API key and bearer token
+   * const client = new ApiClient(
+   *   'https://smartlinks.app/api/v1',
+   *   'your-api-key',
+   *   'your-bearer-token'
+   * );
+   *
+   * // With only API key
+   * const client = new ApiClient(
+   *   'https://smartlinks.app/api/v1',
+   *   'your-api-key'
+   * );
+   *
+   * // With only bearer token
+   * const client = new ApiClient(
+   *   'https://smartlinks.app/api/v1',
+   *   undefined,
+   *   'your-bearer-token'
+   * );
+   */
+  constructor(baseURL: string, apiKey?: string, bearerToken?: string) {
+    this.baseURL = baseURL.replace(/\/+$/, ''); // Trim trailing slash
+    this.apiKey = apiKey;
+    this.bearerToken = bearerToken;
+  }
+
+  /**
+   * Retrieves a single Collection by its ID.
+   * @param collectionId - Identifier of the collection
+   * @returns Promise resolving to a CollectionResponse object
+   * @throws ErrorResponse if the request fails
+   */
+  public async getCollection(collectionId: string): Promise<CollectionResponse> {
+    const path = `/public/collection/${encodeURIComponent(collectionId)}`;
+    return this.request<CollectionResponse>(path);
+  }
+
+  /**
+   * Retrieves a single Product Item by Collection ID and Product ID.
+   * @param collectionId - Identifier of the parent collection
+   * @param productId - Identifier of the product item
+   * @returns Promise resolving to a ProductResponse object
+   * @throws ErrorResponse if the request fails
+   */
+  public async getProductItem(collectionId: string, productId: string): Promise<ProductResponse> {
+    const path = `/public/collection/${encodeURIComponent(collectionId)}/product/${encodeURIComponent(productId)}`;
+    return this.request<ProductResponse>(path);
+  }
+
+  /**
+   * 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
+   */
+  public async getAppConfiguration(collectionId: string, appId: string): Promise<AppConfigurationResponse> {
+    const path = `/public/collection/${encodeURIComponent(collectionId)}/app/${encodeURIComponent(appId)}`;
+    return this.request<AppConfigurationResponse>(path);
+  }
+
+  /**
+   * Internal helper to perform a GET request and parse JSON.
+   * @param path - The path (relative to baseURL) to request
+   * @returns Promise resolving to the parsed JSON of type T
+   * @throws Error if network error or a non-2xx response is returned
+   */
+  private async request<T>(path: string): Promise<T> {
+    const url = `${this.baseURL}${path}`;
+    const headers: Record<string, string> = {
+      'Content-Type': 'application/json',
+    };
+    if (this.apiKey) {
+      headers['X-API-Key'] = this.apiKey;
+    }
+    if (this.bearerToken) {
+      headers['AUTHORIZATION'] = `Bearer ${this.bearerToken}`;
+    }
+
+    const response = await fetch(url, { method: 'GET', headers });
+
+    if (!response.ok) {
+      // Attempt to parse error body; if it fails, throw generic
+      let errorBody: ErrorResponse;
+      try {
+        errorBody = (await response.json()) as ErrorResponse;
+      } catch {
+        throw new Error(`Request failed with status ${response.status}`);
+      }
+      throw new Error(`Error ${errorBody.code}: ${errorBody.message}`);
+    }
+
+    return (await response.json()) as T;
+  }
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "module": "ES6",
+    "moduleResolution": "node",
+    "declaration": true,
+    "outDir": "dist",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": [
+    "src/**/*"
+  ]
+}