@learncard/partner-connect 0.3.7 → 0.3.8

package/README.md

@@ -635,28 +635,28 @@ try {
 ---
 // src/pages/index.astro
 const config = {
-  learnCardHostOrigin: import.meta.env.PUBLIC_LEARNCARD_HOST || 'https://learncard.app'
+    learnCardHostOrigin: import.meta.env.PUBLIC_LEARNCARD_HOST || 'https://learncard.app',
 };
 ---
 
 <script>
-  import { createPartnerConnect } from '@learncard/partner-connect';
-
-  const config = window.__LC_CONFIG;
-  const learnCard = createPartnerConnect({
-    hostOrigin: config.learnCardHostOrigin
-  });
-
-  async function init() {
-    try {
-      const identity = await learnCard.requestIdentity();
-      console.log('Logged in as:', identity.user.did);
-    } catch (error) {
-      console.error('Not authenticated:', error);
+    import { createPartnerConnect } from '@learncard/partner-connect';
+
+    const config = window.__LC_CONFIG;
+    const learnCard = createPartnerConnect({
+        hostOrigin: config.learnCardHostOrigin,
+    });
+
+    async function init() {
+        try {
+            const identity = await learnCard.requestIdentity();
+            console.log('Logged in as:', identity.user.did);
+        } catch (error) {
+            console.error('Not authenticated:', error);
+        }
     }
-  }
 
-  init();
+    init();
 </script>
 ```
 
@@ -736,6 +736,38 @@ import type {
 } from '@learncard/partner-connect';
 ```
 
+## Learner Context Sync Readiness
+
+Apps that need a complete learner snapshot can ask LearnCard to wait for background data sync:
+
+```typescript
+const context = await learnCard.requestLearnerContext({
+    includeCredentials: true,
+    waitForSync: true,
+    format: 'structured',
+});
+
+if (context.status === 'syncing') {
+    const unsubscribe = learnCard.onSyncComplete(async () => {
+        const readyContext = await learnCard.requestLearnerContext({
+            includeCredentials: true,
+            waitForSync: true,
+            format: 'structured',
+        });
+
+        unsubscribe();
+        console.log(readyContext.raw?.credentials);
+    });
+}
+```
+
+Use `learnCard.getSyncStatus()` to render your own progress UI:
+
+```typescript
+const syncStatus = await learnCard.getSyncStatus();
+console.log(syncStatus.status, syncStatus.progress);
+```
+
 ## License
 
 MIT

package/dist/index.d.ts

@@ -312,6 +312,12 @@ interface RequestLearnerContextOptions {
      * @default 'compact'
      */
     detailLevel?: 'compact' | 'expanded';
+    /**
+     * Wait for LearnCard to finish background ConsentFlow data sync before returning context.
+     * Apps that need a complete learner snapshot should set this to true.
+     * @default false
+     */
+    waitForSync?: boolean;
 }
 /**
  * Raw data included in learner context response (when format is 'structured')
@@ -326,6 +332,10 @@ interface LearnerContextRawData {
  * Response from REQUEST_LEARNER_CONTEXT action
  */
 interface LearnerContextResponse {
+    /** Whether the response used immediately available data or waited for a complete sync */
+    status?: 'ready' | 'syncing';
+    /** Current sync progress when available */
+    progress?: SyncProgress;
     /** LLM-ready formatted prompt text */
     prompt: string;
     /** Raw structured data (only included when format is 'structured') */
@@ -335,6 +345,18 @@ interface LearnerContextResponse {
     /** User's display name if available */
     displayName?: string;
 }
+interface SyncProgress {
+    totalCredentials: number;
+    completedCredentials: number;
+    failedCredentials: number;
+    retryCount: number;
+}
+interface SyncStatus {
+    status: 'ready' | 'syncing' | 'error';
+    progress: SyncProgress;
+    eta?: number;
+    lastError?: string;
+}
 /**
  * Keywords for next steps in summary credential data
  */
@@ -587,6 +609,8 @@ declare class PartnerConnect {
     private pendingRequests;
     private messageListener;
     private isInitialized;
+    private syncCompleteCallbacks;
+    private syncStatusPollId;
     constructor(options?: PartnerConnectOptions);
     /**
      * Configure the active host origin using the following hierarchy:
@@ -889,11 +913,19 @@ declare class PartnerConnect {
      * const context = await learnCard.requestLearnerContext({
      *   includeCredentials: true,
      *   includePersonalData: true,
+     *   waitForSync: true,
      *   format: 'prompt',
      *   instructions: 'Focus on technical skills and certifications',
      *   detailLevel: 'expanded'
      * });
      *
+     * if (context.status === 'syncing') {
+     *   const unsubscribe = learnCard.onSyncComplete(async () => {
+     *     const readyContext = await learnCard.requestLearnerContext({ waitForSync: true });
+     *     unsubscribe();
+     *   });
+     * }
+     *
      * // Use in AI system prompt
      * const systemPrompt = `You are a helpful tutor. ${context.prompt}`;
      *
@@ -903,6 +935,18 @@ declare class PartnerConnect {
      * ```
      */
     requestLearnerContext(options?: RequestLearnerContextOptions): Promise<LearnerContextResponse>;
+    /**
+     * Get the current LearnCard background data sync status.
+     */
+    getSyncStatus(): Promise<SyncStatus>;
+    /**
+     * Register a callback that fires when LearnCard reports background sync has reached a
+     * terminal state ('ready' or 'error'). Check `status.status` to distinguish the two.
+     * Polling stops once a terminal state is reached, all callbacks unsubscribe, or the
+     * poll exceeds its maximum duration (reported to callbacks as an 'error' status).
+     * Returns an unsubscribe function.
+     */
+    onSyncComplete(callback: (status: SyncStatus) => void): () => void;
     /**
      * Send a generic event to be processed by the brain service on behalf of this app.
      * This is used for backend-like operations such as issuing credentials.
@@ -977,4 +1021,4 @@ declare class PartnerConnect {
  */
 declare function createPartnerConnect(options?: PartnerConnectOptions): PartnerConnect;
 
-export { AppNotificationInput, AppNotificationResponse, CheckCredentialInput, CheckCredentialResponse, CheckIssuanceStatusInput, ConsentResponse, CredentialSearchResponse, CredentialSpecificResponse, ErrorCode, GetCounterResponse, GetCountersResponse, GetTemplateRecipientsInput, IdentityResponse, IncrementCounterResponse, LearnCardError, LearnerContextRawData, LearnerContextResponse, PartnerConnect, PartnerConnectError, PartnerConnectOptions, PendingRequest, PostMessageRequest, PostMessageResponse, RequestConsentOptions, RequestConsentPayload, RequestLearnerContextOptions, SendAiSessionCredentialInput, SendAiSessionCredentialResponse, SendCredentialResponse, SummaryCredentialData, SummaryCredentialKeyword, SummaryCredentialNextStep, SummaryCredentialReflection, SummaryCredentialSkill, TemplateCredentialInput, TemplateCredentialResponse, TemplateIssuanceStatusResponse, TemplateIssueResponse, TemplateRecipientRecord, TemplateRecipientsResponse, VPRQuery, VerifiablePresentationRequest, createPartnerConnect, createPartnerConnect as default };
+export { AppNotificationInput, AppNotificationResponse, CheckCredentialInput, CheckCredentialResponse, CheckIssuanceStatusInput, ConsentResponse, CredentialSearchResponse, CredentialSpecificResponse, ErrorCode, GetCounterResponse, GetCountersResponse, GetTemplateRecipientsInput, IdentityResponse, IncrementCounterResponse, LearnCardError, LearnerContextRawData, LearnerContextResponse, PartnerConnect, PartnerConnectError, PartnerConnectOptions, PendingRequest, PostMessageRequest, PostMessageResponse, RequestConsentOptions, RequestConsentPayload, RequestLearnerContextOptions, SendAiSessionCredentialInput, SendAiSessionCredentialResponse, SendCredentialResponse, SummaryCredentialData, SummaryCredentialKeyword, SummaryCredentialNextStep, SummaryCredentialReflection, SummaryCredentialSkill, SyncProgress, SyncStatus, TemplateCredentialInput, TemplateCredentialResponse, TemplateIssuanceStatusResponse, TemplateIssueResponse, TemplateRecipientRecord, TemplateRecipientsResponse, VPRQuery, VerifiablePresentationRequest, createPartnerConnect, createPartnerConnect as default };

package/dist/partner-connect.esm.js

@@ -34,6 +34,7 @@ class PartnerConnectError extends Error {
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+const SYNC_STATUS_POLL_MAX_DURATION_MS = 10 * 60 * 1e3;
 const _PartnerConnect = class _PartnerConnect {
   constructor(options) {
     __publicField(this, "hostOrigins", ["https://learncard.app"]);
@@ -44,6 +45,8 @@ const _PartnerConnect = class _PartnerConnect {
     __publicField(this, "pendingRequests");
     __publicField(this, "messageListener", null);
     __publicField(this, "isInitialized", false);
+    __publicField(this, "syncCompleteCallbacks", /* @__PURE__ */ new Set());
+    __publicField(this, "syncStatusPollId", null);
     var _a, _b;
     const hostOrigin = (_a = options == null ? void 0 : options.hostOrigin) != null ? _a : _PartnerConnect.DEFAULT_HOST_ORIGIN;
     const configured = Array.isArray(hostOrigin) ? hostOrigin : [hostOrigin];
@@ -162,10 +165,7 @@ const _PartnerConnect = class _PartnerConnect {
     let candidateUrl;
     try {
       patternUrl = new URL(
-        pattern.replace(
-          _PartnerConnect.WILDCARD_REGEX,
-          _PartnerConnect.WILDCARD_PLACEHOLDER
-        )
+        pattern.replace(_PartnerConnect.WILDCARD_REGEX, _PartnerConnect.WILDCARD_PLACEHOLDER)
       );
       candidateUrl = new URL(candidate);
     } catch {
@@ -562,11 +562,19 @@ const _PartnerConnect = class _PartnerConnect {
    * const context = await learnCard.requestLearnerContext({
    *   includeCredentials: true,
    *   includePersonalData: true,
+   *   waitForSync: true,
    *   format: 'prompt',
    *   instructions: 'Focus on technical skills and certifications',
    *   detailLevel: 'expanded'
    * });
    *
+   * if (context.status === 'syncing') {
+   *   const unsubscribe = learnCard.onSyncComplete(async () => {
+   *     const readyContext = await learnCard.requestLearnerContext({ waitForSync: true });
+   *     unsubscribe();
+   *   });
+   * }
+   *
    * // Use in AI system prompt
    * const systemPrompt = `You are a helpful tutor. ${context.prompt}`;
    *
@@ -576,15 +584,70 @@ const _PartnerConnect = class _PartnerConnect {
    * ```
    */
   requestLearnerContext(options) {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e;
     return this.sendMessage("REQUEST_LEARNER_CONTEXT", {
       includeCredentials: (_a = options == null ? void 0 : options.includeCredentials) != null ? _a : true,
       includePersonalData: (_b = options == null ? void 0 : options.includePersonalData) != null ? _b : false,
       format: (_c = options == null ? void 0 : options.format) != null ? _c : "prompt",
       instructions: options == null ? void 0 : options.instructions,
-      detailLevel: (_d = options == null ? void 0 : options.detailLevel) != null ? _d : "compact"
+      detailLevel: (_d = options == null ? void 0 : options.detailLevel) != null ? _d : "compact",
+      waitForSync: (_e = options == null ? void 0 : options.waitForSync) != null ? _e : false
     });
   }
+  /**
+   * Get the current LearnCard background data sync status.
+   */
+  getSyncStatus() {
+    return this.sendMessage("GET_SYNC_STATUS");
+  }
+  /**
+   * Register a callback that fires when LearnCard reports background sync has reached a
+   * terminal state ('ready' or 'error'). Check `status.status` to distinguish the two.
+   * Polling stops once a terminal state is reached, all callbacks unsubscribe, or the
+   * poll exceeds its maximum duration (reported to callbacks as an 'error' status).
+   * Returns an unsubscribe function.
+   */
+  onSyncComplete(callback) {
+    this.syncCompleteCallbacks.add(callback);
+    if (!this.syncStatusPollId) {
+      const pollStartedAt = Date.now();
+      const stopPolling = () => {
+        if (this.syncStatusPollId) {
+          clearInterval(this.syncStatusPollId);
+          this.syncStatusPollId = null;
+        }
+      };
+      this.syncStatusPollId = setInterval(() => {
+        if (Date.now() - pollStartedAt > SYNC_STATUS_POLL_MAX_DURATION_MS) {
+          stopPolling();
+          const timeoutStatus = {
+            status: "error",
+            progress: {
+              totalCredentials: 0,
+              completedCredentials: 0,
+              failedCredentials: 0,
+              retryCount: 0
+            },
+            lastError: "Timed out waiting for sync to complete"
+          };
+          this.syncCompleteCallbacks.forEach((cb) => cb(timeoutStatus));
+          return;
+        }
+        this.getSyncStatus().then((status) => {
+          if (status.status !== "ready" && status.status !== "error") return;
+          stopPolling();
+          this.syncCompleteCallbacks.forEach((cb) => cb(status));
+        }).catch(() => void 0);
+      }, 1e3);
+    }
+    return () => {
+      this.syncCompleteCallbacks.delete(callback);
+      if (this.syncCompleteCallbacks.size === 0 && this.syncStatusPollId) {
+        clearInterval(this.syncStatusPollId);
+        this.syncStatusPollId = null;
+      }
+    };
+  }
   /**
    * Send a generic event to be processed by the brain service on behalf of this app.
    * This is used for backend-like operations such as issuing credentials.
@@ -683,6 +746,11 @@ const _PartnerConnect = class _PartnerConnect {
       );
     }
     this.pendingRequests.clear();
+    if (this.syncStatusPollId) {
+      clearInterval(this.syncStatusPollId);
+      this.syncStatusPollId = null;
+    }
+    this.syncCompleteCallbacks.clear();
     this.isInitialized = false;
   }
 };