@proofchain/sdk 2.17.0 → 2.20.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
@@ -1682,6 +1747,21 @@ var QuestsClient = class {
   async getUserProgress(questId, userId) {
     return this.http.get(`/quests/${questId}/progress/${encodeURIComponent(userId)}`);
   }
+  /**
+   * Mark a quest step as in-progress (started).
+   *
+   * Call this when the user clicks a CTA link to begin a challenge.
+   * Sets the step to 'in_progress' status so the frontend can show
+   * a pending state while waiting for the completion event to fire.
+   *
+   * Idempotent — safe to call multiple times for the same step.
+   */
+  async startStep(questId, userId, stepIndex) {
+    return this.http.post(
+      `/quests/${questId}/progress/${encodeURIComponent(userId)}/step/${stepIndex}/start`,
+      {}
+    );
+  }
   /**
    * Complete a step manually by step index
    */
@@ -1700,7 +1780,7 @@ var QuestsClient = class {
   /**
    * Claim a completed quest reward.
    * Only applicable for quests with reward_mode='claimable'.
-   * Transitions the quest from REWARD_CLAIMABLE to REWARD_PENDING/COMPLETED
+   * Transitions the quest from COMPLETED to CLAIMED
    * and awards points + creates the earned reward.
    */
   async claimReward(questId, userId) {
@@ -2097,6 +2177,7 @@ 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 = {};
@@ -2187,6 +2268,312 @@ var NotificationsClient = class {
       }
     };
   }
+  // ===========================================================================
+  // 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
@@ -2487,6 +2874,7 @@ var ProofChain = class _ProofChain {
     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).
@@ -2820,6 +3208,7 @@ export {
   CertificatesResource,
   ChannelsResource,
   CohortLeaderboardClient,
+  CredentialsClient,
   DataViewsClient,
   DocumentsResource,
   EndUserIngestionClient,

package/package.json

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