@learncard/partner-connect 0.5.2 → 0.6.0

package/src/origin-resolution.test.ts

@@ -341,6 +341,235 @@ describe('incoming message validation', () => {
     });
 });
 
+// ---------------------------------------------------------------------------
+// Publish-origin resolution (lc_publish_override)
+// ---------------------------------------------------------------------------
+
+describe('publish-origin resolution hierarchy', () => {
+    const mocked = { mock: true as const, mockOptions: { ui: false, log: false } };
+
+    test('mockOptions.publishOrigin outranks lc_publish_override', () => {
+        installLocation({ search: '?lc_publish_override=https://staging.learncard.app' });
+
+        const sdk = new PartnerConnect({
+            mock: true,
+            mockOptions: { ui: false, log: false, publishOrigin: 'https://explicit.learncard.app' },
+        });
+
+        expect(sdk.getPublishOrigin()).toBe('https://explicit.learncard.app');
+
+        sdk.destroy();
+    });
+
+    test('lc_publish_override outranks lc_host_override', () => {
+        installLocation({
+            search: '?lc_host_override=https://alpha.vetpass.app&lc_publish_override=http://localhost:3000',
+        });
+
+        const sdk = new PartnerConnect(mocked);
+
+        expect(sdk.getPublishOrigin()).toBe('http://localhost:3000');
+
+        sdk.destroy();
+    });
+
+    test('a stored lc_publish_override still outranks an lc_host_override param', () => {
+        window.sessionStorage.setItem('lc_publish_override', 'http://localhost:3000');
+        installLocation({ search: '?lc_host_override=https://alpha.vetpass.app' });
+
+        const sdk = new PartnerConnect(mocked);
+
+        expect(sdk.getPublishOrigin()).toBe('http://localhost:3000');
+
+        sdk.destroy();
+    });
+
+    test('falls back to a concrete lc_host_override when no publish override exists', () => {
+        installLocation({ search: '?lc_host_override=https://alpha.vetpass.app' });
+
+        const sdk = new PartnerConnect(mocked);
+
+        expect(sdk.getPublishOrigin()).toBe('https://alpha.vetpass.app');
+
+        sdk.destroy();
+    });
+
+    test('uses a stored lc_host_override when no query params are present', () => {
+        window.sessionStorage.setItem('lc_host_override', 'https://alpha.vetpass.app');
+        installLocation({ search: '' });
+
+        const sdk = new PartnerConnect(mocked);
+
+        expect(sdk.getPublishOrigin()).toBe('https://alpha.vetpass.app');
+
+        sdk.destroy();
+    });
+
+    test('ignores a wildcard lc_host_override and infers from configured origins', () => {
+        installLocation({ search: '?lc_host_override=https://*.learncard.app' });
+
+        const sdk = new PartnerConnect({
+            ...mocked,
+            hostOrigin: 'https://staging.learncard.app',
+            disableDefaultTenants: true,
+        });
+
+        expect(sdk.getPublishOrigin()).toBe('https://staging.learncard.app');
+
+        sdk.destroy();
+    });
+
+    test('infers the first concrete configured origin, skipping wildcards', () => {
+        installLocation({ search: '' });
+
+        const sdk = new PartnerConnect({
+            ...mocked,
+            hostOrigin: ['https://*.learncard.app', 'https://staging.learncard.app'],
+            disableDefaultTenants: true,
+        });
+
+        expect(sdk.getPublishOrigin()).toBe('https://staging.learncard.app');
+
+        sdk.destroy();
+    });
+
+    test('falls back to the default publish origin when nothing else applies', () => {
+        installLocation({ search: '' });
+
+        const sdk = new PartnerConnect(mocked);
+
+        expect(sdk.getPublishOrigin()).toBe('https://learncard.app');
+
+        sdk.destroy();
+    });
+
+    test('applies to non-mock instances too', () => {
+        installLocation({ search: '?lc_publish_override=http://localhost:3000' });
+
+        const sdk = new PartnerConnect({ mock: false });
+
+        expect(sdk.getPublishOrigin()).toBe('http://localhost:3000');
+
+        sdk.destroy();
+    });
+
+    test('normalizes a full URL down to its origin', () => {
+        installLocation({
+            search: `?lc_publish_override=${encodeURIComponent(
+                'http://localhost:3000/app-store/developer?foo=bar'
+            )}`,
+        });
+
+        const sdk = new PartnerConnect(mocked);
+
+        expect(sdk.getPublishOrigin()).toBe('http://localhost:3000');
+
+        sdk.destroy();
+    });
+});
+
+describe('invalid lc_publish_override values', () => {
+    const mocked = { mock: true as const, mockOptions: { ui: false, log: false } };
+
+    test.each([['not-a-url'], ['ftp://example.com'], ['//learncard.app'], ['javascript:alert(1)']])(
+        'ignores %s with a warning and falls through',
+        value => {
+            installLocation({ search: `?lc_publish_override=${encodeURIComponent(value)}` });
+
+            const sdk = new PartnerConnect({
+                ...mocked,
+                hostOrigin: 'https://staging.learncard.app',
+                disableDefaultTenants: true,
+            });
+
+            expect(sdk.getPublishOrigin()).toBe('https://staging.learncard.app');
+            expect(consoleWarnSpy).toHaveBeenCalledWith(
+                expect.stringContaining('lc_publish_override is not a valid http(s) origin'),
+                value
+            );
+
+            sdk.destroy();
+        }
+    );
+
+    test('an invalid value still lets a concrete lc_host_override through', () => {
+        installLocation({
+            search: '?lc_publish_override=nope&lc_host_override=https://alpha.vetpass.app',
+        });
+
+        const sdk = new PartnerConnect(mocked);
+
+        expect(sdk.getPublishOrigin()).toBe('https://alpha.vetpass.app');
+
+        sdk.destroy();
+    });
+
+    test('a corrupt stored value is ignored rather than thrown on', () => {
+        window.sessionStorage.setItem('lc_publish_override', 'not-a-url');
+        installLocation({ search: '' });
+
+        const sdk = new PartnerConnect(mocked);
+
+        expect(sdk.getPublishOrigin()).toBe('https://learncard.app');
+
+        sdk.destroy();
+    });
+});
+
+describe('lc_publish_override sessionStorage persistence', () => {
+    const mocked = { mock: true as const, mockOptions: { ui: false, log: false } };
+
+    test('persists a valid override so later navigations keep it', () => {
+        installLocation({ search: '?lc_publish_override=http://localhost:3000' });
+
+        const first = new PartnerConnect(mocked);
+        expect(window.sessionStorage.getItem('lc_publish_override')).toBe('http://localhost:3000');
+        first.destroy();
+
+        // A later page load in the same tab, without the query parameter.
+        installLocation({ search: '' });
+
+        const second = new PartnerConnect(mocked);
+        expect(second.getPublishOrigin()).toBe('http://localhost:3000');
+        second.destroy();
+    });
+
+    test('persists the normalized origin, not the raw value', () => {
+        installLocation({
+            search: `?lc_publish_override=${encodeURIComponent('http://localhost:3000/submit')}`,
+        });
+
+        const sdk = new PartnerConnect(mocked);
+
+        expect(window.sessionStorage.getItem('lc_publish_override')).toBe('http://localhost:3000');
+
+        sdk.destroy();
+    });
+
+    test('does not persist an invalid value', () => {
+        installLocation({ search: '?lc_publish_override=not-a-url' });
+
+        const sdk = new PartnerConnect(mocked);
+
+        expect(window.sessionStorage.getItem('lc_publish_override')).toBeNull();
+
+        sdk.destroy();
+    });
+
+    test('is stored separately from lc_host_override', () => {
+        installLocation({
+            search: '?lc_host_override=https://alpha.vetpass.app&lc_publish_override=http://localhost:3000',
+        });
+
+        const sdk = new PartnerConnect(mocked);
+
+        expect(window.sessionStorage.getItem('lc_host_override')).toBe('https://alpha.vetpass.app');
+        expect(window.sessionStorage.getItem('lc_publish_override')).toBe('http://localhost:3000');
+
+        sdk.destroy();
+    });
+});
+
 // ---------------------------------------------------------------------------
 // Native-app origins
 // ---------------------------------------------------------------------------

package/src/types.ts

@@ -2,13 +2,42 @@
  * LearnCard Partner Connect SDK - Type Definitions
  */
 
-// Re-export AppEvent types from shared types package
-export type {
-    AppEvent,
-    SendCredentialEvent,
+import type {
+    AppEvent as BaseAppEvent,
+    AppEventResponse as BaseAppEventResponse,
     CheckCredentialEvent,
-    AppEventResponse,
+    SendCredentialEvent as BaseSendCredentialEvent,
 } from '@learncard/types';
+import type {
+    CapturedAppManifest,
+    ConsentRequest,
+    InlineCredentialTemplate,
+    InlineTemplateValidationError,
+} from '@learncard/partner-connect-core';
+
+// Re-export AppEvent types from shared types package
+export type { CheckCredentialEvent };
+export type {
+    CapturedAppManifest,
+    CapturedConsentRecord,
+    CapturedTemplateRecord,
+    CompiledInlineTemplate,
+    ConsentRequest,
+    InlineCredentialTemplate,
+    InlineTemplateValidationError,
+    PersonalField,
+    RawInlineCredentialTemplate,
+    SimpleInlineCredentialTemplate,
+    VariableManifest,
+    WalletCategory,
+} from '@learncard/partner-connect-core';
+
+export interface PreviewCompiledTemplateResult {
+    valid: boolean;
+    errors: InlineTemplateValidationError[];
+    compiled?: Record<string, unknown>;
+    rendered?: Record<string, unknown>;
+}
 
 /**
  * Configuration options for initializing the SDK
@@ -112,15 +141,17 @@ export interface PartnerConnectOptions {
      * 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
+     *    AND the app is running in local dev** (`localhost`, `127.0.0.1`,
+     *    `[::1]`, `*.localhost`, `*.local`) **or an AI app builder's editor
+     *    preview** (Lovable, Bolt, v0, Replit). This covers local dev, local
+     *    Storybook, and building in those tools, but deliberately never
+     *    fabricates identity or consent on a published or deploy-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
+     *    any origin — including remote deploy previews (Netlify, 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.
@@ -186,6 +217,21 @@ export interface MockHostOptions {
      */
     persist?: boolean;
 
+    /**
+     * Show the mock-mode "Publish to LearnCard" nudge once the captured app
+     * manifest becomes publishable.
+     *
+     * @default true
+     */
+    publishPrompt?: boolean;
+
+    /**
+     * LearnCard origin used to build the App Store submission URL.
+     *
+     * @default 'https://learncard.app'
+     */
+    publishOrigin?: string;
+
     /**
      * The fake DID returned by `requestIdentity()` (and used as the mock
      * user's identity) while in mock mode.
@@ -203,6 +249,13 @@ export interface MockHostOptions {
      */
     namespace?: string;
 
+    /**
+     * Distinguishes your app from other apps served on the same origin
+     * (e.g. multiple projects on localhost:4321). Defaults to a fingerprint
+     * of the initial document.title.
+     */
+    appId?: string;
+
     /**
      * Seed the mock user's identity. Superseded per-field over the legacy
      * `did` option. Extra fields are returned as-is from `requestIdentity()`.
@@ -259,6 +312,16 @@ export interface MockCredentialSeed {
     status?: 'pending' | 'claimed' | 'revoked';
 }
 
+/** Public manifest snapshot getter, available only while mock mode is active. */
+export interface CapturedManifestReadable {
+    getCapturedManifest(): CapturedAppManifest | undefined;
+    getPublishUrl(): string | undefined;
+    /** Start fresh for the current practice app; no-op outside mock mode. */
+    resetPracticeMode(): void;
+    getActiveHostOrigin(): string | null;
+    getPublishOrigin(): string | null;
+}
+
 /**
  * Identity information returned from REQUEST_IDENTITY
  */
@@ -295,6 +358,56 @@ export interface TemplateCredentialInput {
     preventDuplicateClaim?: boolean;
 }
 
+/**
+ * Inline credential template input for sendCredential.
+ *
+ * This sends the full template definition to LearnCard at runtime, with no
+ * pre-configured host template required.
+ *
+ * @example
+ * ```typescript
+ * await learnCard.sendCredential({
+ *   alias: 'course-complete',
+ *   template: {
+ *     name: 'Completed {{courseName}}',
+ *     description: 'Awarded for finishing {{courseName}}.',
+ *     achievementType: 'Course',
+ *     criteria: { narrative: 'Finished all modules' }
+ *   },
+ *   templateData: { courseName: 'Intro to Baking' }
+ * });
+ * ```
+ */
+export interface InlineTemplateCredentialInput {
+    /** App-scoped alias used for duplicate checks and inline template versioning. */
+    alias: string;
+
+    /** Inline credential template definition compiled by LearnCard at issuance time. */
+    template: InlineCredentialTemplate;
+
+    /** Runtime values for the template variables. */
+    templateData?: Record<string, unknown>;
+
+    /**
+     * If true, the host will return an existing credential (if present) instead of issuing a duplicate.
+     */
+    preventDuplicateClaim?: boolean;
+}
+
+/** Inline `send-credential` app event for zero-config issuance. */
+export interface InlineTemplateSendCredentialEvent {
+    type: 'send-credential';
+    alias: string;
+    template: InlineCredentialTemplate;
+    templateData?: Record<string, unknown>;
+    preventDuplicateClaim?: boolean;
+}
+
+export type SendCredentialEvent = BaseSendCredentialEvent | InlineTemplateSendCredentialEvent;
+export type AppEvent = BaseAppEvent | InlineTemplateSendCredentialEvent;
+export type AppEventResponse = BaseAppEventResponse;
+export type SendCredentialInput = unknown | TemplateCredentialInput | InlineTemplateCredentialInput;
+
 /**
  * Response from template-based credential issuance
  */
@@ -317,6 +430,9 @@ export interface TemplateCredentialResponse {
     /** The date the credential was received (when preventDuplicateClaim is true) */
     receivedDate?: string;
 
+    /** Version number for inline templates sharing the same alias. */
+    templateVersion?: number;
+
     [key: string]: unknown;
 }
 
@@ -382,6 +498,7 @@ export interface RequestConsentPayload {
      * to use the contract configured for the current app listing.
      */
     contractUri?: string;
+    scopes?: ConsentRequest;
     redirect?: boolean;
 }
 
@@ -724,6 +841,8 @@ export type ErrorCode =
     | 'CREDENTIAL_NOT_FOUND'
     | 'USER_REJECTED'
     | 'UNAUTHORIZED'
+    | 'TEMPLATE_INVALID'
+    | 'TEMPLATE_DATA_INVALID'
     | 'TEMPLATE_NOT_FOUND'
     | 'BOOST_NOT_FOUND'
     | 'INSUFFICIENT_PERMISSIONS'