@proofchain/sdk 2.16.0 → 2.19.0

package/dist/index.mjs

@@ -1559,6 +1559,71 @@ var RewardsClient = class {
   async listAssets(definitionId) {
     return this.http.get(`/rewards/definitions/${definitionId}/assets`);
   }
+  // ---------------------------------------------------------------------------
+  // Reward Attestations
+  // ---------------------------------------------------------------------------
+  /**
+   * Create a signed attestation for an earned reward.
+   *
+   * Binds the reward to the user's wallet with an EIP-712 signature.
+   * The anchoring mode is determined by the reward definition or tenant config.
+   *
+   * @param earnedRewardId - The earned reward ID to attest
+   * @returns The attestation details including signature and on-chain status
+   *
+   * @example
+   * ```ts
+   * const attestation = await client.rewards.attest('earned-reward-id');
+   * console.log(attestation.attestation_uid, attestation.status);
+   * ```
+   */
+  async attest(earnedRewardId) {
+    return this.http.post(`/rewards/earned/${earnedRewardId}/attest`, {});
+  }
+  /**
+   * Anchor an earned reward's attestation on-chain (on-demand).
+   *
+   * The reward must already have a signed attestation.
+   * Writes the attestation hash to the Base blockchain contract.
+   *
+   * @param earnedRewardId - The earned reward ID whose attestation to anchor
+   *
+   * @example
+   * ```ts
+   * const result = await client.rewards.anchor('earned-reward-id');
+   * console.log('Anchored on-chain:', result.tx_hash);
+   * ```
+   */
+  async anchor(earnedRewardId) {
+    return this.http.post(`/rewards/earned/${earnedRewardId}/anchor`, {});
+  }
+  /**
+   * Get the attestation for an earned reward.
+   *
+   * @param earnedRewardId - The earned reward ID
+   */
+  async getAttestation(earnedRewardId) {
+    return this.http.get(`/rewards/earned/${earnedRewardId}/attestation`);
+  }
+  /**
+   * Verify a reward attestation's signature and on-chain status.
+   *
+   * @param earnedRewardId - The earned reward ID to verify
+   *
+   * @example
+   * ```ts
+   * const result = await client.rewards.verifyAttestation('earned-reward-id');
+   * if (result.is_valid) {
+   *   console.log('Reward is cryptographically verified!');
+   *   if (result.on_chain) {
+   *     console.log('Also anchored on Base:', result.tx_hash);
+   *   }
+   * }
+   * ```
+   */
+  async verifyAttestation(earnedRewardId) {
+    return this.http.get(`/rewards/earned/${earnedRewardId}/verify`);
+  }
 };
 
 // src/quests.ts
@@ -2094,6 +2159,408 @@ var FanpassLeaderboardClient = class {
   }
 };
 
+// src/notifications.ts
+var NotificationsClient = class {
+  constructor(http) {
+    this.http = http;
+    this.baseUrl = http.baseUrl || "https://api.proofchain.co.za";
+    this.authHeaders = () => {
+      const headers = {};
+      if (http.apiKey) {
+        headers["X-API-Key"] = http.apiKey;
+      }
+      if (http.userToken) {
+        headers["Authorization"] = `Bearer ${http.userToken}`;
+        if (http.tenantId) {
+          headers["X-Tenant-ID"] = http.tenantId;
+        }
+      }
+      return headers;
+    };
+  }
+  /**
+   * Subscribe to real-time notifications for a user.
+   *
+   * Opens a Server-Sent Events connection and calls the callback
+   * for each notification event (quest progress, rewards, etc.).
+   *
+   * Returns an unsubscribe function to close the connection.
+   *
+   * **Browser usage:** Works out of the box with EventSource.
+   * **Node.js usage:** Requires the `eventsource` package.
+   *
+   * @param userId - The external user ID to subscribe for
+   * @param callback - Function called for each notification event
+   * @param options - Connection options (reconnect, callbacks)
+   * @returns Unsubscribe function to close the connection
+   */
+  subscribe(userId, callback, options = {}) {
+    const {
+      onConnect,
+      onDisconnect,
+      onError,
+      autoReconnect = true,
+      reconnectDelay = 3e3
+    } = options;
+    let eventSource = null;
+    let closed = false;
+    let reconnectTimer = null;
+    const connect = () => {
+      if (closed) return;
+      const headers = this.authHeaders();
+      const params = new URLSearchParams({ user_id: userId });
+      if (headers["X-API-Key"]) {
+        params.append("api_key", headers["X-API-Key"]);
+      }
+      if (headers["Authorization"]) {
+        params.append("token", headers["Authorization"].replace("Bearer ", ""));
+      }
+      if (headers["X-Tenant-ID"]) {
+        params.append("tenant_id", headers["X-Tenant-ID"]);
+      }
+      const url = `${this.baseUrl}/notifications/stream?${params.toString()}`;
+      const ES = typeof EventSource !== "undefined" ? EventSource : (() => {
+        throw new Error('EventSource not available. Install the "eventsource" package for Node.js.');
+      })();
+      eventSource = new ES(url);
+      eventSource.onmessage = (e) => {
+        try {
+          const event = JSON.parse(e.data);
+          if (event.event === "connected") {
+            onConnect?.();
+          } else {
+            callback(event);
+          }
+        } catch (err) {
+          onError?.(new Error(`Failed to parse notification: ${e.data}`));
+        }
+      };
+      eventSource.onerror = () => {
+        if (closed) return;
+        onDisconnect?.();
+        if (eventSource?.readyState === 2 && autoReconnect) {
+          reconnectTimer = setTimeout(connect, reconnectDelay);
+        }
+      };
+    };
+    connect();
+    return () => {
+      closed = true;
+      if (reconnectTimer) clearTimeout(reconnectTimer);
+      if (eventSource) {
+        eventSource.close();
+        eventSource = null;
+      }
+    };
+  }
+  // ===========================================================================
+  // WEB PUSH (OS-level notifications, even when browser is closed)
+  // ===========================================================================
+  /**
+   * Get the tenant's VAPID public key for Web Push.
+   *
+   * This key is needed to call `pushManager.subscribe()` in the browser.
+   * Returns null if Web Push is not configured for this tenant.
+   */
+  async getVapidKey() {
+    try {
+      const res = await this.http.get("/notifications/push/vapid-key");
+      return res.vapid_public_key;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Register a browser push subscription with the server.
+   *
+   * Call this after the user grants notification permission and you
+   * obtain a PushSubscription from `pushManager.subscribe()`.
+   *
+   * @param userId - External user ID
+   * @param subscription - The PushSubscription object (or its JSON)
+   * @returns Subscription ID from the server
+   */
+  async registerPush(userId, subscription) {
+    const json = "toJSON" in subscription ? subscription.toJSON() : subscription;
+    return this.http.post(
+      "/notifications/push/subscribe",
+      {
+        user_id: userId,
+        endpoint: json.endpoint,
+        keys: json.keys,
+        user_agent: typeof navigator !== "undefined" ? navigator.userAgent : void 0
+      }
+    );
+  }
+  /**
+   * Remove a push subscription from the server.
+   *
+   * Call this when the user logs out or revokes notification permission.
+   *
+   * @param userId - External user ID
+   * @param endpoint - The push endpoint URL to remove
+   */
+  async unregisterPush(userId, endpoint) {
+    return this.http.post(
+      "/notifications/push/unsubscribe",
+      { user_id: userId, endpoint }
+    );
+  }
+  /**
+   * High-level helper: request permission, subscribe to push, and register.
+   *
+   * Handles the full Web Push registration flow:
+   * 1. Fetches the VAPID public key from the server
+   * 2. Requests notification permission from the user
+   * 3. Registers a Service Worker (if not already registered)
+   * 4. Subscribes to push via the Push API
+   * 5. Sends the subscription to the server
+   *
+   * @param userId - External user ID
+   * @param serviceWorkerPath - Path to the service worker file (default: '/sw.js')
+   * @returns The PushSubscription, or null if denied/unavailable
+   *
+   * @example
+   * ```typescript
+   * const sub = await client.notifications.requestPermissionAndSubscribe(
+   *   'user-123',
+   *   '/proofchain-sw.js'
+   * );
+   * if (sub) {
+   *   console.log('Push notifications enabled!');
+   * }
+   * ```
+   */
+  async requestPermissionAndSubscribe(userId, serviceWorkerPath = "/sw.js") {
+    if (typeof window === "undefined" || !("serviceWorker" in navigator) || !("PushManager" in window)) {
+      console.warn("Web Push is not supported in this browser");
+      return null;
+    }
+    const vapidKey = await this.getVapidKey();
+    if (!vapidKey) {
+      console.warn("Web Push not configured for this tenant");
+      return null;
+    }
+    const permission = await Notification.requestPermission();
+    if (permission !== "granted") {
+      console.warn("Notification permission denied");
+      return null;
+    }
+    const registration = await navigator.serviceWorker.register(serviceWorkerPath);
+    await navigator.serviceWorker.ready;
+    const applicationServerKey = this._urlBase64ToUint8Array(vapidKey);
+    const pushSubscription = await registration.pushManager.subscribe({
+      userVisibleOnly: true,
+      applicationServerKey: applicationServerKey.buffer
+    });
+    await this.registerPush(userId, pushSubscription);
+    return pushSubscription;
+  }
+  /**
+   * Generate a basic Service Worker script for handling push notifications.
+   *
+   * Returns JavaScript source code that can be saved as your sw.js file.
+   * The generated worker handles `push` events (shows notification) and
+   * `notificationclick` events (opens the app).
+   *
+   * @param defaultIcon - Optional default icon URL for notifications
+   * @param defaultUrl - URL to open when notification is clicked (default: '/')
+   * @returns Service Worker JavaScript source code as a string
+   *
+   * @example
+   * ```typescript
+   * // Save the output as /public/sw.js in your project
+   * const swCode = client.notifications.generateServiceWorker({
+   *   defaultIcon: '/icon-192.png',
+   *   defaultUrl: '/',
+   * });
+   * ```
+   */
+  generateServiceWorker(options = {}) {
+    const { defaultIcon = "/icon-192.png", defaultUrl = "/" } = options;
+    return `// ProofChain Push Notification Service Worker
+// Auto-generated \u2014 place this file at the root of your public directory
+
+self.addEventListener('push', function(event) {
+  if (!event.data) return;
+
+  let payload;
+  try {
+    payload = event.data.json();
+  } catch (e) {
+    payload = { title: 'Notification', body: event.data.text() };
+  }
+
+  const options = {
+    body: payload.body || '',
+    icon: payload.icon || '${defaultIcon}',
+    badge: payload.badge || '${defaultIcon}',
+    data: {
+      url: payload.url || '${defaultUrl}',
+      ...payload.data,
+    },
+    tag: payload.data?.event || 'proofchain',
+    renotify: true,
+  };
+
+  event.waitUntil(
+    self.registration.showNotification(payload.title || 'Notification', options)
+  );
+});
+
+self.addEventListener('notificationclick', function(event) {
+  event.notification.close();
+  const url = event.notification.data?.url || '${defaultUrl}';
+
+  event.waitUntil(
+    clients.matchAll({ type: 'window', includeUncontrolled: true }).then(function(clientList) {
+      // Focus existing tab if open
+      for (const client of clientList) {
+        if (client.url === url && 'focus' in client) {
+          return client.focus();
+        }
+      }
+      // Otherwise open new tab
+      return clients.openWindow(url);
+    })
+  );
+});
+`;
+  }
+  /** Convert a base64url-encoded VAPID key to a Uint8Array for the Push API. */
+  _urlBase64ToUint8Array(base64String) {
+    const padding = "=".repeat((4 - base64String.length % 4) % 4);
+    const base64 = (base64String + padding).replace(/-/g, "+").replace(/_/g, "/");
+    const rawData = atob(base64);
+    const outputArray = new Uint8Array(rawData.length);
+    for (let i = 0; i < rawData.length; ++i) {
+      outputArray[i] = rawData.charCodeAt(i);
+    }
+    return outputArray;
+  }
+};
+
+// src/credentials.ts
+var CredentialsClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  // ---------------------------------------------------------------------------
+  // Credential Types
+  // ---------------------------------------------------------------------------
+  /**
+   * Create a new credential type
+   */
+  async createType(request) {
+    return this.http.post("/credentials/types", request);
+  }
+  /**
+   * List credential types
+   */
+  async listTypes(options) {
+    return this.http.get("/credentials/types", {
+      status: options?.status,
+      category: options?.category
+    });
+  }
+  /**
+   * Get a specific credential type
+   */
+  async getType(typeId) {
+    return this.http.get(`/credentials/types/${typeId}`);
+  }
+  /**
+   * Update a credential type
+   */
+  async updateType(typeId, request) {
+    return this.http.put(`/credentials/types/${typeId}`, request);
+  }
+  /**
+   * Activate a credential type
+   */
+  async activateType(typeId) {
+    return this.http.post(`/credentials/types/${typeId}/activate`, {});
+  }
+  /**
+   * Archive a credential type
+   */
+  async archiveType(typeId) {
+    return this.http.post(`/credentials/types/${typeId}/archive`, {});
+  }
+  // ---------------------------------------------------------------------------
+  // Credential Issuance
+  // ---------------------------------------------------------------------------
+  /**
+   * Issue a credential to a user
+   */
+  async issue(request) {
+    return this.http.post("/credentials/issue", request);
+  }
+  /**
+   * List issued credentials
+   */
+  async listIssued(options) {
+    return this.http.get("/credentials/issued", {
+      user_id: options?.user_id,
+      credential_type_id: options?.credential_type_id,
+      status: options?.status,
+      limit: options?.limit,
+      offset: options?.offset
+    });
+  }
+  /**
+   * Revoke an issued credential
+   */
+  async revoke(credentialId, reason) {
+    const params = reason ? `?reason=${encodeURIComponent(reason)}` : "";
+    return this.http.post(`/credentials/issued/${credentialId}/revoke${params}`, {});
+  }
+  /**
+   * Suspend an issued credential
+   */
+  async suspend(credentialId, reason) {
+    const params = reason ? `?reason=${encodeURIComponent(reason)}` : "";
+    return this.http.post(`/credentials/issued/${credentialId}/suspend${params}`, {});
+  }
+  /**
+   * Reinstate a suspended credential
+   */
+  async reinstate(credentialId) {
+    return this.http.post(`/credentials/issued/${credentialId}/reinstate`, {});
+  }
+  // ---------------------------------------------------------------------------
+  // User Management
+  // ---------------------------------------------------------------------------
+  /**
+   * Opt a user in to identity credentials (tenant admin)
+   */
+  async optInUser(userExternalId) {
+    return this.http.post(`/credentials/opt-in/${userExternalId}`, {});
+  }
+  /**
+   * Opt a user out of identity credentials (tenant admin)
+   */
+  async optOutUser(userExternalId) {
+    return this.http.post(`/credentials/opt-out/${userExternalId}`, {});
+  }
+  /**
+   * Get all credentials for a user
+   */
+  async getUserCredentials(userExternalId) {
+    return this.http.get(`/credentials/user/${userExternalId}`);
+  }
+  // ---------------------------------------------------------------------------
+  // Public Verification (no auth needed)
+  // ---------------------------------------------------------------------------
+  /**
+   * Verify a credential by its verification code.
+   * This is a public endpoint — no authentication required.
+   */
+  async verify(verificationCode) {
+    return this.http.get(`/credentials/verify/${verificationCode}`);
+  }
+};
+
 // src/client.ts
 var DocumentsResource = class {
   constructor(http) {
@@ -2391,6 +2858,8 @@ var ProofChain = class _ProofChain {
     this.dataViews = new DataViewsClient(this.http);
     this.cohorts = new CohortLeaderboardClient(this.http);
     this.fanpassLeaderboard = new FanpassLeaderboardClient(this.http);
+    this.notifications = new NotificationsClient(this.http);
+    this.credentials = new CredentialsClient(this.http);
   }
   /**
    * Create a client for end-user JWT authentication (PWA/frontend use).
@@ -2724,6 +3193,7 @@ export {
   CertificatesResource,
   ChannelsResource,
   CohortLeaderboardClient,
+  CredentialsClient,
   DataViewsClient,
   DocumentsResource,
   EndUserIngestionClient,
@@ -2733,6 +3203,7 @@ export {
   IngestionClient,
   NetworkError,
   NotFoundError,
+  NotificationsClient,
   PassportClient,
   ProofChain,
   ProofChainError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@proofchain/sdk",
-  "version": "2.16.0",
+  "version": "2.19.0",
   "description": "Official JavaScript/TypeScript SDK for ProofChain - blockchain-anchored document attestation",
   "main": "dist/index.js",
   "module": "dist/index.mjs",