@learncard/partner-connect 0.3.10 → 0.4.0

package/README.md

@@ -77,6 +77,25 @@ interface PartnerConnectOptions {
      * Request timeout in milliseconds (default: 30000)
      */
     requestTimeout?: number;
+
+    /**
+     * Controls automatic standalone mock mode.
+     * 'auto' (default) mocks only when no LearnCard host is present AND the
+     * page runs on a local dev host; 'standalone' mocks whenever no host is
+     * present, on any origin; true always mocks; false never mocks.
+     */
+    mock?: boolean | 'auto' | 'standalone';
+
+    /**
+     * Fine-grained mock behavior (UI, logging, persistence, fake DID).
+     */
+    mockOptions?: MockHostOptions;
+
+    /**
+     * How long (ms) to wait for the host presence probe when embedded in a
+     * frame whose parent can't be confirmed as LearnCard (default: 1500).
+     */
+    hostProbeTimeout?: number;
 }
 ```
 
@@ -166,6 +185,169 @@ The SDK enforces an exact match between incoming message origins and the active
 // ❌ Rejects: messages from any other origin
 ```
 
+## Standalone / Mock Mode
+
+The SDK only works when embedded inside a LearnCard host — that's the host that
+answers its `postMessage` requests. When you run your app on its own (local dev,
+Storybook, a preview deploy, CI), there is no host. Standalone calls that aren't
+mocked reject immediately with `LC_NOT_EMBEDDED` (rather than hanging until the
+request timeout), and the SDK logs a one-time hint pointing you to mock mode.
+
+**Mock mode fixes this automatically in local development.** Whenever no
+LearnCard host is present and your app runs on a local dev host (`localhost`,
+`127.0.0.1`, `[::1]`, `*.localhost`, `*.local`) — plain local dev or a local
+Storybook — the SDK simulates the host locally:
+
+-   **Every method shows a branded toast** describing what would happen once embedded — e.g. `sendCredential` → _"✅ In LearnCard, the user would receive **[name]** here."_, `incrementCounter` → _"Counter **coins** → **10**."_, `launchFeature` → _"Would open **/wallet**."_ So you get strong, visible feedback for every call, not just console logs.
+-   `requestConsent(...)` auto-grants and shows a "mock consent" toast; `incrementCounter` / `getCounter` / `getCounters` persist to `localStorage` so values survive reloads.
+-   Identical or polled calls **coalesce** into a single toast with a ×N counter, so nothing spams the screen.
+-   `requestIdentity`, notifications, learner context, sync status, etc. all resolve with sensible fake data.
+-   Every simulated interaction is also logged to the console with a `[LearnCard SDK · MOCK]` prefix.
+
+**No code changes, no environment flags in local dev.** Your app is fully
+buildable and demo-able locally, and behaves identically against the real host
+once embedded.
+
+```typescript
+// Mocks in local dev when standalone; real host when embedded in LearnCard.
+const learnCard = createPartnerConnect({ hostOrigin: 'https://learncard.app' });
+
+const res = await learnCard.sendCredential({ templateAlias: 'course-completion' });
+// Local dev, standalone: resolves with a mock URI + shows a toast.
+// Embedded:              goes to the real LearnCard host.
+```
+
+**`'auto'` is deliberately scoped to local dev hosts.** A standalone page on a
+production or remote preview origin never auto-mocks — otherwise a real user
+opening your app's URL directly would receive a fabricated identity and
+auto-granted consent. For remote deploy previews (Netlify, Lovable, Vercel, …)
+that should demo standalone anywhere but go real once embedded, opt in with
+`mock: 'standalone'`; for CI and tests that should always mock, use
+`mock: true`. Every mocked call shows a labeled toast and a
+`[LearnCard SDK · MOCK]` console log, so it's clear the SDK is simulating
+rather than talking to a real host.
+
+| `mock`             | Standalone, local dev | Standalone, remote origin     | Embedded in LearnCard |
+| ------------------ | --------------------- | ----------------------------- | --------------------- |
+| `'auto'` (default) | mock                  | fail fast (`LC_NOT_EMBEDDED`) | real host             |
+| `'standalone'`     | mock                  | mock                          | real host             |
+| `true`             | mock                  | mock                          | mock                  |
+| `false`            | fail fast             | fail fast                     | real host             |
+
+**Unrelated iframes don't fool it.** If your app is embedded in something that
+isn't LearnCard (a cross-origin Storybook canvas, a preview shell), calls no
+longer hang: the SDK mocks on local dev hosts and otherwise rejects fast with
+`LC_NOT_EMBEDDED`. When the parent can't be identified (Firefox, or a
+same-origin localhost wrapper), the SDK sends a one-time, side-effect-free
+presence probe and only mocks if no host answers within `hostProbeTimeout`
+(default 1500 ms).
+
+For a **production build that's meant to run only inside LearnCard**, set
+`mock: false`; standalone calls then reject immediately with `LC_NOT_EMBEDDED`
+instead of showing simulated data.
+
+Override the default behavior when needed:
+
+```typescript
+// Mock wherever no host is present (remote previews), real host when embedded:
+createPartnerConnect({ mock: 'standalone' });
+
+// Always mock, even while embedded (CI, tests):
+createPartnerConnect({ mock: true });
+
+// Never mock (standalone calls reject fast with LC_NOT_EMBEDDED):
+createPartnerConnect({ mock: false });
+
+// Configure mock behavior:
+createPartnerConnect({
+    mock: 'auto',
+    mockOptions: {
+        ui: true, // show toasts/banners (default true)
+        log: true, // console logging (default true)
+        persist: true, // localStorage-backed counters (default true)
+        did: 'did:web:example.com:me', // fake identity DID
+        namespace: 'my-app-mock', // localStorage namespace for mock state
+    },
+});
+```
+
+Check whether an instance is currently mocking:
+
+```typescript
+if (learnCard.isMocked()) {
+    console.log('Running against the local mock host.');
+}
+```
+
+### Coherent state: reads reflect writes
+
+The mock keeps a small session store so it behaves like a real host, not a set of
+disconnected stubs. Anything you do in a session shows up in later reads:
+
+```typescript
+await learnCard.sendCredential({ templateAlias: 'course-completion' });
+
+// Now reflects the credential you just issued:
+await learnCard.checkUserHasCredential({ templateAlias: 'course-completion' }); // { hasCredential: true, ... }
+await learnCard.requestLearnerContext(); // raw.credentials includes it
+```
+
+This means happy-path UI (e.g. a "you already earned this" banner) actually
+lights up standalone. Counters persist to `localStorage`; issued credentials and
+identity live for the session (a reload re-applies your seeds — see below). Mock
+credentials are clearly marked (`_mock: true`) and never cryptographically valid,
+so they can't be mistaken for real ones.
+
+### Seeding data for demos
+
+To demo a pre-populated state (a returning user who already has credentials, a
+starting coin balance) without performing actions first, seed via `mockOptions`:
+
+```typescript
+createPartnerConnect({
+    mockOptions: {
+        identity: { did: 'did:web:example.com:me', name: 'Ada' },
+        credentials: [
+            { templateAlias: 'course-completion', name: 'Algebra 101' },
+            // Model a credential you issued to someone else:
+            { boostUri: 'lc:boost:team-badge', recipient: 'alice', status: 'pending' },
+        ],
+        counters: { coins: 50 },
+    },
+});
+```
+
+Seeded credentials feed `checkUserHasCredential`, `getTemplateRecipients`,
+`getTemplateIssuanceStatus`, `requestLearnerContext`, and `askCredentialSearch`.
+Seeded counters are applied only when a counter has no persisted value yet, so
+incremented values survive reloads.
+
+## Detecting the Embed Context
+
+Use `isEmbedded()` to branch your own logic based on whether your app is running
+inside a LearnCard iframe or as a standalone page — no need to write your own
+frame detection.
+
+```typescript
+import { isEmbedded, createPartnerConnect } from '@learncard/partner-connect';
+
+if (isEmbedded()) {
+    // Inside LearnCard — hide your standalone header, enable SDK-backed features.
+} else {
+    // Standalone — show an "Open in LearnCard" prompt, or lean on mock mode.
+}
+```
+
+It is also available as a static and instance method:
+
+```typescript
+PartnerConnect.isEmbedded(); // static
+createPartnerConnect().isEmbedded(); // instance
+```
+
+`isEmbedded()` returns `false` during server-side rendering (no `window`) and is
+safe to call anywhere.
+
 ## API Reference
 
 ### `requestIdentity()`
@@ -181,6 +363,7 @@ const identity = await learnCard.requestIdentity();
 
 -   `LC_UNAUTHENTICATED`: User is not logged in to LearnCard
 -   `LC_TIMEOUT`: Request timed out
+-   `LC_NOT_EMBEDDED`: The app is not embedded in a LearnCard host (standalone, not mocking)
 
 ---
 
@@ -601,6 +784,7 @@ interface LearnCardError {
 **Common Error Codes:**
 
 -   `LC_TIMEOUT`: Request timed out
+-   `LC_NOT_EMBEDDED`: Not embedded in a LearnCard host (standalone, not mocking)
 -   `LC_UNAUTHENTICATED`: User not logged in
 -   `USER_REJECTED`: User declined the request
 -   `CREDENTIAL_NOT_FOUND`: Credential doesn't exist

package/dist/index.d.ts

@@ -91,6 +91,146 @@ interface PartnerConnectOptions {
      * Request timeout in milliseconds (default: 30000)
      */
     requestTimeout?: number;
+    /**
+     * Controls automatic **standalone mock mode**.
+     *
+     * When the SDK runs outside of a LearnCard host (i.e. as a top-level page,
+     * not embedded in an iframe), there is no host to answer `postMessage`
+     * requests, so every call would hang until it times out. Mock mode makes
+     * the SDK simulate the host locally so your app is fully buildable,
+     * demo-able, and testable without being embedded — and then behaves
+     * identically (real host) once embedded, with no code changes.
+     *
+     * - `'auto'` **(default)**: mock only when **no LearnCard host is present
+     *    AND the app is running on a local dev host** (`localhost`,
+     *    `127.0.0.1`, `[::1]`, `*.localhost`, `*.local`). This covers local
+     *    dev and local Storybook, but deliberately never fabricates identity
+     *    or consent on a production or preview origin. Each mocked call
+     *    surfaces a labeled toast plus a console log so it's clear the host
+     *    is simulated.
+     * - `'standalone'`: mock whenever **no LearnCard host is present**, on
+     *    any origin — including remote deploy previews (Netlify, Lovable,
+     *    Vercel, …) — and use the real host when embedded in LearnCard. The
+     *    one-flag setting for apps that must demo standalone anywhere. Only
+     *    choose it when a user opening your app's URL directly should see
+     *    simulated data.
+     * - `true`: always mock, **even when embedded in a real LearnCard host**.
+     *    Use this for CI and tests; for previews that should go real once
+     *    embedded, prefer `'standalone'`.
+     * - `false`: never mock. Standalone calls reject immediately with
+     *    `LC_NOT_EMBEDDED`. Set this in production builds meant to run only
+     *    inside LearnCard.
+     *
+     * @default 'auto'
+     */
+    mock?: boolean | 'auto' | 'standalone';
+    /**
+     * Fine-grained configuration for standalone mock mode. Ignored when mock
+     * mode is not active. See {@link MockHostOptions}.
+     */
+    mockOptions?: MockHostOptions;
+    /**
+     * How long (ms) to wait for the host to answer the one-time presence
+     * probe used when the SDK is embedded in an iframe whose parent cannot
+     * be confirmed as LearnCard (e.g. a same-origin Storybook canvas on
+     * localhost). Only used with `mock: 'auto'` on local dev hosts.
+     *
+     * @default 1500
+     */
+    hostProbeTimeout?: number;
+}
+/**
+ * Options controlling the behavior of standalone mock mode.
+ *
+ * All fields are optional; mock mode works out-of-the-box with sensible
+ * defaults (visible UI, console logging, and localStorage-backed counters).
+ */
+interface MockHostOptions {
+    /**
+     * Render lightweight visual feedback in the page: a fake credential-claim
+     * modal / toast for `sendCredential`, and a "mock consent" banner for
+     * `requestConsent`. Set to `false` for a headless mock (logs only).
+     *
+     * @default true
+     */
+    ui?: boolean;
+    /**
+     * Log every simulated host interaction to the console with a clear
+     * `[LearnCard SDK · MOCK]` prefix.
+     *
+     * @default true
+     */
+    log?: boolean;
+    /**
+     * Persist counters (`incrementCounter` / `getCounter` / `getCounters`) to
+     * `localStorage` so values survive page reloads, mirroring the real host's
+     * durable per-user counters. Falls back to in-memory storage when
+     * `localStorage` is unavailable.
+     *
+     * @default true
+     */
+    persist?: boolean;
+    /**
+     * The fake DID returned by `requestIdentity()` (and used as the mock
+     * user's identity) while in mock mode.
+     *
+     * @default 'did:web:mock.learncard.app:user'
+     */
+    did?: string;
+    /**
+     * Namespace used to scope persisted mock data (counters, claimed
+     * credentials) in `localStorage`. Change this if you run multiple mock
+     * apps on the same origin and want isolated state.
+     *
+     * @default 'lc-mock'
+     */
+    namespace?: string;
+    /**
+     * Seed the mock user's identity. Superseded per-field over the legacy
+     * `did` option. Extra fields are returned as-is from `requestIdentity()`.
+     */
+    identity?: MockIdentitySeed;
+    /**
+     * Pre-populate the mock with credentials the user already holds (or has
+     * issued to others). This lets you demo "happy path" states — e.g. a
+     * "you already earned this" banner — without performing an action first.
+     * Reads like `checkUserHasCredential`, `getTemplateRecipients`,
+     * `requestLearnerContext`, and `askCredentialSearch` reflect these.
+     */
+    credentials?: MockCredentialSeed[];
+    /**
+     * Initial counter values, applied only when a counter has no persisted
+     * value yet (so incremented values survive reloads).
+     */
+    counters?: Record<string, number>;
+}
+/**
+ * Seed shape for the mock user's identity (see {@link MockHostOptions.identity}).
+ */
+interface MockIdentitySeed {
+    did?: string;
+    name?: string;
+    [key: string]: unknown;
+}
+/**
+ * Seed shape for a pre-populated mock credential (see
+ * {@link MockHostOptions.credentials}).
+ */
+interface MockCredentialSeed {
+    /** Template alias this credential was issued from. */
+    templateAlias?: string;
+    /** Boost URI this credential was issued from. */
+    boostUri?: string;
+    /** Human-readable credential name (used in toasts and mock VC data). */
+    name?: string;
+    /**
+     * Recipient identifier (profileId or DID). Defaults to the mock user
+     * (i.e. a credential the user holds). Set this to model credentials the
+     * user has issued to other people.
+     */
+    recipient?: string;
+    /** Claim status. @default 'claimed' */
+    status?: 'pending' | 'claimed' | 'revoked';
 }
 /**
  * Identity information returned from REQUEST_IDENTITY
@@ -499,7 +639,7 @@ interface GetCountersResponse {
 /**
  * Error codes that can be returned by the LearnCard host
  */
-type ErrorCode = 'LC_TIMEOUT' | 'LC_UNAUTHENTICATED' | 'CREDENTIAL_NOT_FOUND' | 'USER_REJECTED' | 'UNAUTHORIZED' | 'TEMPLATE_NOT_FOUND' | 'BOOST_NOT_FOUND' | 'INSUFFICIENT_PERMISSIONS' | string;
+type ErrorCode = 'LC_TIMEOUT' | 'LC_NOT_EMBEDDED' | 'LC_UNAUTHENTICATED' | 'CREDENTIAL_NOT_FOUND' | 'USER_REJECTED' | 'UNAUTHORIZED' | 'TEMPLATE_NOT_FOUND' | 'BOOST_NOT_FOUND' | 'INSUFFICIENT_PERMISSIONS' | string;
 /**
  * Error object returned when a request fails.
  *
@@ -598,6 +738,28 @@ interface PendingRequest {
  * ```
  */
 
+/**
+ * Detect whether the current page is running inside an embedded iframe.
+ *
+ * Returns `true` when the SDK is embedded (e.g. inside the LearnCard host) and
+ * `false` when running as a standalone top-level page. Safe to call in any
+ * environment: returns `false` during server-side rendering (no `window`).
+ *
+ * Partner apps can use this to change behavior without writing their own frame
+ * detection — for example, showing a "Open in LearnCard" prompt when standalone.
+ *
+ * @example
+ * ```typescript
+ * import { isEmbedded } from '@learncard/partner-connect';
+ *
+ * if (isEmbedded()) {
+ *   // Running inside LearnCard — use the SDK against the real host.
+ * } else {
+ *   // Standalone — show a preview banner, or rely on automatic mock mode.
+ * }
+ * ```
+ */
+declare function isEmbedded(): boolean;
 /**
  * LearnCard Partner Connect SDK class
  */
@@ -627,7 +789,47 @@ declare class PartnerConnect {
     private isInitialized;
     private syncCompleteCallbacks;
     private syncStatusPollId;
+    private mockHost;
+    private embedded;
+    private warnedNoHost;
+    private hostProbeTimeout;
+    /** Whether a real LearnCard host is believed to be listening. */
+    private hostReachable;
+    /** Pending probe decision; requests queue behind it when set. */
+    private activation;
     constructor(options?: PartnerConnectOptions);
+    /**
+     * Decide whether this instance talks to a real host, simulates one, or
+     * fails fast — the resolution of the `mock` option against the runtime
+     * embed context. See the `mock` option docs for the contract.
+     */
+    private configureMockActivation;
+    private isLocalDevContext;
+    private classifyParent;
+    private matchesConfiguredOrigin;
+    /**
+     * One-time host presence probe for the ambiguous-parent case. Sends a
+     * side-effect-free `GET_SYNC_STATUS`; an answer proves a live LearnCard
+     * host (responses are origin-checked), a timeout means nobody is
+     * listening and the mock takes over. Requests issued while the probe is
+     * in flight queue behind the decision instead of racing it.
+     */
+    private probeHost;
+    /**
+     * Whether this SDK instance is running inside an embedded iframe.
+     * Instance-level convenience wrapper around the standalone {@link isEmbedded}.
+     */
+    isEmbedded(): boolean;
+    /**
+     * Whether the current page is running inside an embedded iframe.
+     * Static convenience wrapper around the standalone {@link isEmbedded}.
+     */
+    static isEmbedded(): boolean;
+    /**
+     * Whether this instance is currently simulating the LearnCard host locally
+     * instead of talking to a real host over `postMessage`.
+     */
+    isMocked(): boolean;
     /**
      * Configure the active host origin using the following hierarchy:
      * 1. `window.location.ancestorOrigins[0]` (when supported) — the browser's
@@ -705,9 +907,13 @@ declare class PartnerConnect {
      */
     private generateRequestId;
     /**
-     * Send a message to the parent window and return a Promise
+     * Send a message to the parent window and return a Promise. While a host
+     * presence probe is pending, requests queue behind its decision so they
+     * are answered by whichever side (real host or mock) actually exists.
      */
     private sendMessage;
+    private dispatchMessage;
+    private postToHost;
     /**
      * Request user identity (Single Sign-On)
      *
@@ -1037,4 +1243,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, LearnerContextCacheStatus, LearnerContextRawData, LearnerContextResponse, LearnerContextTimingBreakdown, 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 };
+export { AppNotificationInput, AppNotificationResponse, CheckCredentialInput, CheckCredentialResponse, CheckIssuanceStatusInput, ConsentResponse, CredentialSearchResponse, CredentialSpecificResponse, ErrorCode, GetCounterResponse, GetCountersResponse, GetTemplateRecipientsInput, IdentityResponse, IncrementCounterResponse, LearnCardError, LearnerContextCacheStatus, LearnerContextRawData, LearnerContextResponse, LearnerContextTimingBreakdown, MockCredentialSeed, MockHostOptions, MockIdentitySeed, 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, isEmbedded };