@proveanything/smartlinks 1.0.28 → 1.0.30

package/README.md

@@ -0,0 +1,430 @@
+# Smartlinks SDK
+
+Official JavaScript/TypeScript SDK for the Smartlinks API - enabling digital product authentication, traceability, and engagement.
+
+## Installation
+
+```bash
+npm install @proveanything/smartlinks
+```
+
+## Quick Start
+
+```typescript
+import { initializeApi, auth, collection, product } from '@proveanything/smartlinks'
+
+// Initialize the SDK
+initializeApi({
+  baseURL: 'https://smartlinks.app/api/v1'
+})
+
+// Login
+const loginResponse = await auth.login('email@example.com', 'password')
+
+// Get collections
+const collections = await collection.list(true) // admin endpoint
+
+// Get products in a collection
+const products = await product.list('collection-id', true)
+
+// Get a specific product
+const productDetail = await product.get('collection-id', 'product-id')
+```
+
+## Configuration
+
+### Basic Setup
+
+```typescript
+import { initializeApi } from '@proveanything/smartlinks'
+
+// Initialize with base URL
+initializeApi({
+  baseURL: 'https://smartlinks.app/api/v1'
+})
+
+// Or with API key for server-side usage
+initializeApi({
+  baseURL: 'https://smartlinks.app/api/v1',
+  apiKey: 'your-api-key'
+})
+
+// For iframe/embedded usage
+initializeApi({
+  baseURL: 'https://smartlinks.app/api/v1',
+  proxyMode: true
+})
+```
+
+### Runtime Token Management
+
+```typescript
+import { setBearerToken } from '@proveanything/smartlinks'
+
+// Set token after login
+setBearerToken('your-bearer-token')
+
+// Clear token on logout
+setBearerToken(undefined)
+```
+
+## Authentication
+
+```typescript
+import { auth } from '@proveanything/smartlinks'
+
+// Login with email/password
+const response = await auth.login('user@example.com', 'password')
+console.log(response.bearerToken) // Token is automatically set for future calls
+
+// Verify current token
+const userInfo = await auth.verifyToken()
+
+// Get account information
+const account = await auth.getAccount()
+
+// Logout (clears token)
+auth.logout()
+```
+
+## Working with Collections
+
+Collections are the top-level containers for organizing products.
+
+```typescript
+import { collection } from '@proveanything/smartlinks'
+
+// Get all collections (public)
+const publicCollections = await collection.list(false)
+
+// Get all collections (admin - requires authentication)
+const adminCollections = await collection.list(true)
+
+// Get specific collection
+const col = await collection.get('collection-id', true)
+
+// Create collection (admin only)
+const newCollection = await collection.create({
+  title: 'New Collection',
+  description: 'Collection description'
+})
+
+// Update collection (admin only) 
+await collection.update('collection-id', { 
+  title: 'Updated Title' 
+})
+
+// Delete collection (admin only)
+await collection.remove('collection-id')
+```
+
+### Serial Number Management
+
+```typescript
+// Get serial numbers for a collection
+const serialNumbers = await collection.getSN('collection-id', 0, 10)
+
+// Look up a specific serial number
+const lookupResult = await collection.lookupSN('collection-id', 'serial-code')
+
+// Assign a value to a serial number
+await collection.assignSN('collection-id', 'serial-code', 'assigned-value')
+```
+
+## Working with Products
+
+Products represent individual items within collections.
+
+```typescript
+import { product } from '@proveanything/smartlinks'
+
+// List products in collection (public)
+const publicProducts = await product.list('collection-id', false)
+
+// List products in collection (admin)
+const adminProducts = await product.list('collection-id', true)
+
+// Get specific product
+const prod = await product.get('collection-id', 'product-id')
+
+// Create product (admin only)
+const newProduct = await product.create('collection-id', {
+  name: 'New Product',
+  description: 'Product description',
+  data: {
+    custom: 'properties'
+  }
+})
+
+// Update product (admin only)
+await product.update('collection-id', 'product-id', { 
+  name: 'Updated Name' 
+})
+
+// Delete product (admin only)
+await product.remove('collection-id', 'product-id')
+```
+
+### Product Serial Numbers
+
+```typescript
+// Get serial numbers for a product
+const serialNumbers = await product.getSN('collection-id', 'product-id', 0, 10)
+
+// Look up a serial number for a product
+const lookupResult = await product.lookupSN('collection-id', 'product-id', 'serial-code')
+```
+
+## Variants and Batches
+
+Manage product variants and production batches:
+
+```typescript
+import { variant, batch } from '@proveanything/smartlinks'
+
+// Work with variants
+const variants = await variant.list('collection-id', 'product-id')
+const newVariant = await variant.create('collection-id', 'product-id', {
+  name: 'Size Large',
+  properties: { size: 'L', color: 'blue' }
+})
+
+// Work with batches  
+const batches = await batch.list('collection-id', 'product-id')
+const newBatch = await batch.create('collection-id', 'product-id', {
+  name: 'Batch 001',
+  quantity: 100
+})
+
+// Serial numbers for variants/batches
+const variantSerials = await variant.getSN('collection-id', 'product-id', 'variant-id')
+const batchSerials = await batch.getSN('collection-id', 'product-id', 'batch-id')
+```
+
+## Asset Management
+
+Upload and manage files associated with collections, products, and proofs:
+
+```typescript
+import { asset } from '@proveanything/smartlinks'
+
+// Upload asset to a proof
+const file = document.getElementById('fileInput').files[0]
+const uploadResult = await asset.uploadAsset(
+  'collection-id', 
+  'product-id', 
+  'proof-id', 
+  file,
+  { description: 'Product image' }, // Optional extra data
+  (percent) => console.log(`Upload: ${percent}%`) // Progress callback
+)
+
+// Get asset information
+const assetInfo = await asset.getForProof('collection-id', 'product-id', 'proof-id', 'asset-id')
+
+// List all assets for a proof
+const proofAssets = await asset.listForProof('collection-id', 'product-id', 'proof-id')
+```
+
+## Attestations and Claims
+
+Manage digital attestations and claim verification:
+
+```typescript
+import { attestation, claimSet } from '@proveanything/smartlinks'
+
+// Work with attestations
+const attestations = await attestation.list('collection-id', 'product-id', 'proof-id')
+const newAttestation = await attestation.create('collection-id', 'product-id', 'proof-id', {
+  public: { verified: true },
+  private: { inspector: 'John Doe' },
+  proof: { signature: 'abc123' }
+})
+
+// Work with claim sets
+const claimSets = await claimSet.getAllForCollection('collection-id')
+const claimResult = await claimSet.makeClaim('collection-id', {
+  productId: 'product-id',
+  claimType: 'ownership'
+})
+```
+
+## Proofs
+
+Retrieve and validate product proofs:
+
+```typescript
+import { proof } from '@proveanything/smartlinks'
+
+// Get all proofs for a collection
+const proofs = await proof.list('collection-id')
+
+// Get specific proof
+const proofDetail = await proof.get('collection-id', 'proof-id')
+```
+
+## Forms
+
+Dynamic form creation and management:
+
+```typescript
+import { form } from '@proveanything/smartlinks'
+
+// List forms (public)
+const publicForms = await form.list('collection-id', false)
+
+// List forms (admin)
+const adminForms = await form.list('collection-id', true)
+
+// Create form (admin only)
+const newForm = await form.create('collection-id', {
+  name: 'Product Registration',
+  fields: [
+    { name: 'email', type: 'email', required: true },
+    { name: 'name', type: 'text', required: true }
+  ]
+})
+```
+
+## Advanced Usage
+
+### Proxy Mode (iframe Communication)
+
+When running in an iframe, use proxy mode to communicate with the parent window:
+
+```typescript
+import { initializeApi, sendCustomProxyMessage } from '@proveanything/smartlinks'
+
+// Initialize in proxy mode
+initializeApi({
+  baseURL: 'https://smartlinks.app/api/v1',
+  proxyMode: true
+})
+
+// Send custom messages to parent window
+const response = await sendCustomProxyMessage('custom-action', {
+  data: 'any-data'
+})
+```
+
+### Custom Configuration
+
+```typescript
+import { appConfiguration } from '@proveanything/smartlinks'
+
+// Get configuration
+const config = await appConfiguration.getConfig({ key: 'setting-name' })
+
+// Set configuration
+await appConfiguration.setConfig({ 
+  key: 'setting-name', 
+  value: 'setting-value' 
+})
+
+// Work with configuration data
+const data = await appConfiguration.getData({ category: 'user-preferences' })
+```
+
+## Error Handling
+
+```typescript
+import { ErrorResponse } from '@proveanything/smartlinks'
+
+try {
+  const result = await product.get('collection-id', 'product-id')
+} catch (error) {
+  if (error instanceof ErrorResponse) {
+    console.error('API Error:', error.message)
+    console.error('Status Code:', error.code)
+  } else {
+    console.error('Unexpected error:', error)
+  }
+}
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and includes full type definitions:
+
+```typescript
+import { 
+  ProductResponse, 
+  CollectionResponse, 
+  AttestationCreateRequest 
+} from '@proveanything/smartlinks'
+
+const product: ProductResponse = await product.get('col-id', 'prod-id')
+const collection: CollectionResponse = await collection.get('col-id')
+
+const attestationData: AttestationCreateRequest = {
+  public: { verified: true },
+  private: { notes: 'Internal notes' },
+  proof: { signature: 'digital-signature' }
+}
+```
+
+## Admin vs Public Endpoints
+
+Many functions support both admin and public access modes:
+
+```typescript
+// Public access (limited data, no authentication required)
+const publicCollections = await collection.list(false)
+const publicProducts = await product.list('collection-id', false)
+
+// Admin access (full data + management capabilities, authentication required)  
+const adminCollections = await collection.list(true)
+const adminProducts = await product.list('collection-id', true)
+
+// Create/Update/Delete operations are admin-only
+await collection.create(data) // Requires authentication
+await product.update('col-id', 'prod-id', data) // Requires authentication
+```
+
+## Browser vs Node.js
+
+The SDK works in both browser and Node.js environments:
+
+### Browser Usage
+
+```html
+<script type="module">
+  import { initializeApi, auth } from '@proveanything/smartlinks'
+  
+  initializeApi({ baseURL: 'https://smartlinks.app/api/v1' })
+  // Use the SDK...
+</script>
+```
+
+### Node.js Usage
+
+```javascript
+const { initializeApi, auth } = require('@proveanything/smartlinks')
+
+initializeApi({ 
+  baseURL: 'https://smartlinks.app/api/v1',
+  apiKey: process.env.SMARTLINKS_API_KEY 
+})
+```
+
+## Examples
+
+Check out the [examples](./examples/) directory for complete implementation examples:
+
+- [Node.js Demo](./examples/node-demo.ts) - Server-side usage examples
+- [Browser Demo](./examples/browser-demo.html) - Frontend integration examples
+- [React Demo](./examples/react-demo.tsx) - React component examples
+
+## API Reference
+
+For complete API documentation including all functions and types, see [API_SUMMARY.md](./API_SUMMARY.md).
+
+## Support
+
+- **Documentation**: [API Reference](./API_SUMMARY.md)
+- **Issues**: [GitHub Issues](https://github.com/Prove-Anything/smartlinks/issues)
+- **Website**: [smartlinks.app](https://smartlinks.app)
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) for details.

package/dist/api/collection.js

@@ -99,7 +99,7 @@ export var collection;
      * @throws ErrorResponse if the request fails
      */
     async function assignSN(collectionId, codeId, value) {
-        const path = `/admin/collection/${encodeURIComponent(collectionId)}/lookupSN/${encodeURIComponent(codeId)}`;
+        const path = `/admin/collection/${encodeURIComponent(collectionId)}/assignSN/${encodeURIComponent(codeId)}`;
         return post(path, { value });
     }
     collection.assignSN = assignSN;

package/dist/http.d.ts

@@ -54,9 +54,11 @@ export declare function del<T>(path: string, extraHeaders?: Record<string, strin
  */
 export declare function getApiHeaders(): Record<string, string>;
 /**
- * Sends a custom proxy message in proxyMode and waits for a matching reply.
- * @param request - The request type string
- * @param params - The parameters object
+ * Sends a custom proxy message to the parent Smartlinks application when running in an iframe.
+ * This function is used to communicate with the parent window when the SDK is embedded in an iframe
+ * and proxyMode is enabled. It sends a message to the parent and waits for a response.
+ * @param request - The request type string to identify the message type
+ * @param params - The parameters object containing data to send to the parent
  * @returns The data from the proxy response
  */
 export declare function sendCustomProxyMessage<T = any>(request: string, params: any): Promise<T>;

package/dist/http.js

@@ -279,9 +279,11 @@ export function getApiHeaders() {
     return headers;
 }
 /**
- * Sends a custom proxy message in proxyMode and waits for a matching reply.
- * @param request - The request type string
- * @param params - The parameters object
+ * Sends a custom proxy message to the parent Smartlinks application when running in an iframe.
+ * This function is used to communicate with the parent window when the SDK is embedded in an iframe
+ * and proxyMode is enabled. It sends a message to the parent and waits for a response.
+ * @param request - The request type string to identify the message type
+ * @param params - The parameters object containing data to send to the parent
  * @returns The data from the proxy response
  */
 export async function sendCustomProxyMessage(request, params) {

package/package.json

@@ -1,15 +1,30 @@
 {
   "name": "@proveanything/smartlinks",
-  "version": "1.0.28",
+  "version": "1.0.30",
   "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"
+  ],
   "scripts": {
     "build": "tsc",
     "docs": "typedoc",
     "docs:summary": "node generate-api-summary.js",
-    "build:docs": "tsc build-docs.ts --outDir dist && node dist/build-docs.js"
+    "build:docs": "tsc build-docs.ts --outDir dist && node dist/build-docs.js",
+    "prepublishOnly": "npm run build && npm run docs:summary"
   },
+  "keywords": [
+    "smartlinks",
+    "api",
+    "authentication", 
+    "traceability",
+    "blockchain",
+    "typescript",
+    "sdk"
+  ],
   "author": "Glenn Shoosmith",
   "license": "MIT",
   "publishConfig": {
@@ -27,5 +42,6 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/Prove-Anything/smartlinks.git"
-  }
+  },
+  "homepage": "https://smartlinks.app"
 }

package/build-docs.ts

@@ -1,69 +0,0 @@
-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")
-
-import * as fs from "fs";
-import * as path from "path";
-
-// Use process.cwd() to ensure relative to project root
-const docsJsonPath = path.join(process.cwd(), "docs", "documentation.json");
-const readmePath = path.join(process.cwd(), "README.md");
-
-function extractFullApiDocs(json: any): string {
-  // This is a minimal implementation. For a full-featured generator,
-  // parse all namespaces, functions, and types from the TypeDoc JSON.
-  // Here, we just dump the JSON for demonstration.
-  // Replace this with a real markdown generator as needed.
-  return [
-    "# @proveanything/smartlinks",
-    "",
-    "This README is auto-generated from the TypeScript API documentation.",
-    "",
-    "## API Reference",
-    "",
-    "```json",
-    JSON.stringify(json, null, 2),
-    "```",
-    "",
-    "_Replace this with a full markdown generator for production use._"
-  ].join("\n");
-}
-
-function main() {
-  console.log("Looking for docs JSON at:", docsJsonPath);
-  
-  if (!fs.existsSync(docsJsonPath)) {
-    throw new Error("documentation.json not found. Run `npm run docs` first.");
-  }
-  const json = JSON.parse(fs.readFileSync(docsJsonPath, "utf-8"));
-  const markdown = extractFullApiDocs(json);
-  fs.writeFileSync(readmePath, markdown, "utf-8");
-  console.log("README.md generated from API documentation.");
-}
-
-main();

package/debug.log

@@ -1,6 +0,0 @@
-[0602/081836.172:ERROR:registration_protocol_win.cc(108)] CreateFile: The system cannot find the file specified. (0x2)
-[0602/081836.202:ERROR:registration_protocol_win.cc(108)] CreateFile: The system cannot find the file specified. (0x2)
-[0602/081836.512:ERROR:registration_protocol_win.cc(108)] CreateFile: The system cannot find the file specified. (0x2)
-[0602/081858.471:ERROR:registration_protocol_win.cc(108)] CreateFile: The system cannot find the file specified. (0x2)
-[0602/081858.497:ERROR:registration_protocol_win.cc(108)] CreateFile: The system cannot find the file specified. (0x2)
-[0602/081858.832:ERROR:registration_protocol_win.cc(108)] CreateFile: The system cannot find the file specified. (0x2)

package/examples/browser-demo.html

@@ -1,43 +0,0 @@
-<!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 { initializeApi } from '../dist/index.js';
-    import { collection } from '../dist/api/collection.js';
-    import { product } from '../dist/api/product.js';
-    import { proof } from '../dist/api/proof.js';
-
-    async function run() {
-      const apiKey = 'YOUR_API_KEY'; // optional
-      const bearerToken = 'YOUR_BEARER_TOKEN'; // optional
-
-      // Initialize global config for API requests
-      initializeApi({
-        baseURL: 'https://smartlinks.app/api/v1',
-        apiKey,
-        bearerToken,
-      });
-
-      try {
-        const collectionData = await collection.get('abc123');
-        const productData = await product.get('abc123', 'prod789');
-        const proofData = await proof.get('abc123', 'proof456');
-        document.getElementById('output').textContent = JSON.stringify(
-          { collection: collectionData, product: productData, proof: proofData },
-          null,
-          2
-        );
-      } catch (err) {
-        document.getElementById('output').textContent = 'Error: ' + err.message;
-      }
-    }
-    run();
-  </script>
-</body>
-</html>

package/examples/node-demo.ts

@@ -1,50 +0,0 @@
-import { initializeApi } from "../dist/index";
-import { collection } from "../dist/api/collection";
-import { product } from "../dist/api/product";
-import { proof } from "../dist/api/proof";
-import { batch } from "../dist/api/batch";
-
-async function main() {
-  const apiKey = "YOUR_API_KEY"; // optional
-  const bearerToken = "YOUR_BEARER_TOKEN"; // optional
-
-  initializeApi({
-    baseURL: "https://smartlinks.app/api/v1",
-    apiKey,
-    bearerToken,
-  });
-
-  try {
-    const collectionData = await collection.get("abc123");
-    console.log("Collection:", collectionData);
-
-    const productData = await product.get("abc123", "prod789");
-    console.log("Product Item:", productData);
-
-    const proofData = await proof.get("abc123", "proof456");
-    console.log("Proof:", proofData);
-
-    // Batch API examples
-    // Admin operations (requires admin privileges)
-    const batchList = await batch.list("abc123", "prod789");
-    console.log("Batch List:", batchList);
-
-    const newBatch = await batch.create("abc123", "prod789", {
-      name: "New Batch",
-      description: "Example batch creation",
-      status: "active",
-    });
-    console.log("Created Batch:", newBatch);
-
-    const batchData = await batch.get("abc123", "prod789", newBatch.id);
-    console.log("Batch:", batchData);
-
-    // Public batch endpoint (read-only)
-    const publicBatchData = await batch.getPublic("abc123", "prod789", newBatch.id);
-    console.log("Public Batch:", publicBatchData);
-  } catch (err) {
-    console.error("Error fetching data:", err);
-  }
-}
-
-main();