@learncard/partner-connect 0.5.2 → 0.6.1

package/dist/index.d.ts

@@ -1,10 +1,18 @@
-import { AppEventResponse, AppEvent } from '@learncard/types';
-export { AppEvent, AppEventResponse, CheckCredentialEvent, SendCredentialEvent } from '@learncard/types';
+import { InlineTemplateValidationError, CapturedAppManifest, InlineCredentialTemplate, ConsentRequest } from '@learncard/partner-connect-core';
+export { CapturedAppManifest, CapturedConsentRecord, CapturedTemplateRecord, CompiledInlineTemplate, ConsentRequest, InlineCredentialTemplate, InlineTemplateValidationError, PersonalField, RawInlineCredentialTemplate, SimpleInlineCredentialTemplate, VariableManifest, WalletCategory, decodeManifestFromUrl } from '@learncard/partner-connect-core';
+import { SendCredentialEvent as SendCredentialEvent$1, AppEvent as AppEvent$1, AppEventResponse as AppEventResponse$1 } from '@learncard/types';
+export { CheckCredentialEvent } from '@learncard/types';
 
 /**
  * LearnCard Partner Connect SDK - Type Definitions
  */
 
+interface PreviewCompiledTemplateResult {
+    valid: boolean;
+    errors: InlineTemplateValidationError[];
+    compiled?: Record<string, unknown>;
+    rendered?: Record<string, unknown>;
+}
 /**
  * Configuration options for initializing the SDK
  */
@@ -102,15 +110,17 @@ 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.
@@ -170,6 +180,19 @@ interface MockHostOptions {
      * @default true
      */
     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.
@@ -185,6 +208,12 @@ interface MockHostOptions {
      * @default 'lc-mock'
      */
     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()`.
@@ -232,6 +261,15 @@ interface MockCredentialSeed {
     /** Claim status. @default 'claimed' */
     status?: 'pending' | 'claimed' | 'revoked';
 }
+/** Public manifest snapshot getter, available only while mock mode is active. */
+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
  */
@@ -263,6 +301,50 @@ 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' }
+ * });
+ * ```
+ */
+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. */
+interface InlineTemplateSendCredentialEvent {
+    type: 'send-credential';
+    alias: string;
+    template: InlineCredentialTemplate;
+    templateData?: Record<string, unknown>;
+    preventDuplicateClaim?: boolean;
+}
+type SendCredentialEvent = SendCredentialEvent$1 | InlineTemplateSendCredentialEvent;
+type AppEvent = AppEvent$1 | InlineTemplateSendCredentialEvent;
+type AppEventResponse = AppEventResponse$1;
+type SendCredentialInput = unknown | TemplateCredentialInput | InlineTemplateCredentialInput;
 /**
  * Response from template-based credential issuance
  */
@@ -279,6 +361,8 @@ interface TemplateCredentialResponse {
     status?: 'pending' | 'claimed' | 'revoked';
     /** 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;
 }
 /**
@@ -336,6 +420,7 @@ interface RequestConsentPayload {
      * to use the contract configured for the current app listing.
      */
     contractUri?: string;
+    scopes?: ConsentRequest;
     redirect?: boolean;
 }
 /**
@@ -639,7 +724,7 @@ interface GetCountersResponse {
 /**
  * Error codes that can be returned by the LearnCard host
  */
-type ErrorCode = 'LC_TIMEOUT' | 'LC_NOT_EMBEDDED' | '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_INVALID' | 'TEMPLATE_DATA_INVALID' | 'TEMPLATE_NOT_FOUND' | 'BOOST_NOT_FOUND' | 'INSUFFICIENT_PERMISSIONS' | string;
 /**
  * Error object returned when a request fails.
  *
@@ -738,6 +823,14 @@ interface PendingRequest {
  * ```
  */
 
+/**
+ * Compile and optionally render an inline credential template entirely offline.
+ *
+ * `compiled` contains the canonical OBv3 credential object with `{{variables}}`
+ * preserved. If `templateData` is provided and valid, `rendered` contains the
+ * same object with those variables substituted.
+ */
+declare const previewCompiledTemplate: (template: InlineCredentialTemplate, templateData?: Record<string, unknown>) => PreviewCompiledTemplateResult;
 /**
  * Detect whether the current page is running inside an embedded iframe.
  *
@@ -790,6 +883,14 @@ declare class PartnerConnect {
     private syncCompleteCallbacks;
     private syncStatusPollId;
     private mockHost;
+    /** Internal, non-public context handed to every {@link MockHost} we build. */
+    private mockHostContext;
+    /**
+     * Memoized override-derived publish origin. `undefined` means "not looked
+     * up yet"; `null` means "looked up, no usable override". Caching keeps the
+     * warning for an invalid value to a single log per instance.
+     */
+    private pinnedPublishOrigin;
     private embedded;
     private warnedNoHost;
     private hostProbeTimeout;
@@ -798,6 +899,31 @@ declare class PartnerConnect {
     /** Pending probe decision; requests queue behind it when set. */
     private activation;
     constructor(options?: PartnerConnectOptions);
+    private resolveMockOptions;
+    /**
+     * Resolve the LearnCard origin that App Store publish links point at:
+     * 1. `?lc_publish_override=` (query param, then this tab's stored value).
+     * 2. `?lc_host_override=` (query param, then stored) when it names one
+     *    concrete http(s) origin — testing against a host implies publishing
+     *    to it.
+     * 3. The first concrete configured `hostOrigin`.
+     * 4. `DEFAULT_PUBLISH_ORIGIN`.
+     *
+     * `mockOptions.publishOrigin` outranks all of these and is applied by
+     * {@link resolveMockOptions} before this runs.
+     */
+    private resolvePublishOrigin;
+    private readPinnedPublishOrigin;
+    /**
+     * Unlike `lc_host_override`, this is not a security boundary — it only
+     * decides which LearnCard origin publish links target — so any parseable
+     * http(s) origin is accepted rather than being whitelist-checked.
+     */
+    private readPublishOverride;
+    private readHostOverrideForPublish;
+    private static normalizePublishOrigin;
+    private static readSessionValue;
+    private inferPublishOrigin;
     /**
      * Decide whether this instance talks to a real host, simulates one, or
      * fails fast — the resolution of the `mock` option against the runtime
@@ -805,6 +931,14 @@ declare class PartnerConnect {
      */
     private configureMockActivation;
     private isLocalDevContext;
+    /**
+     * Whether the app is running inside an AI app builder's preview (Lovable,
+     * Bolt, v0, Replit): either on a preview-only host, or framed by the
+     * builder's editor. Firefox hides ancestor origins, so the referrer of an
+     * embedded document stands in for the parent origin there.
+     */
+    private isAppBuilderContext;
+    private readReferrerOrigin;
     private classifyParent;
     private matchesConfiguredOrigin;
     /**
@@ -830,6 +964,53 @@ declare class PartnerConnect {
      * instead of talking to a real host over `postMessage`.
      */
     isMocked(): boolean;
+    /**
+     * Read the app manifest captured by standalone mock mode.
+     *
+     * Returns `undefined` when this instance is talking to a real host, or when
+     * mock mode has not captured anything yet.
+     *
+     * @example
+     * ```typescript
+     * const manifest = learnCard.getCapturedManifest();
+     * if (manifest) {
+     *   console.log(manifest.permissions, manifest.templates);
+     * }
+     * ```
+     */
+    getCapturedManifest(): CapturedAppManifest | undefined;
+    /**
+     * Build the LearnCard App Store submission URL for the current captured manifest.
+     *
+     * Returns `undefined` unless mock mode is active and the SDK has captured at
+     * least one manifest interaction. The publish prompt still uses a higher
+     * threshold (at least 1 inline template or at least 2 distinct permissions)
+     * before it auto-nudges the developer.
+     *
+     * @example
+     * ```typescript
+     * const publishUrl = learnCard.getPublishUrl();
+     * if (publishUrl) {
+     *   window.open(publishUrl, '_blank', 'noopener');
+     * }
+     * ```
+     */
+    getPublishUrl(): string | undefined;
+    /** Clears this app's practice captures, credentials and counters. No-op outside mock mode. */
+    resetPracticeMode(): void;
+    /**
+     * Returns the currently active real-host origin, or `null` while standalone
+     * mock mode is active.
+     */
+    getActiveHostOrigin(): string | null;
+    /**
+     * Returns the LearnCard origin used to build App Store publish URLs.
+     *
+     * Point this at a local or staging LearnCard with
+     * `?lc_publish_override=<origin>`; see {@link resolvePublishOrigin} for
+     * the full precedence order.
+     */
+    getPublishOrigin(): string | null;
     /**
      * Configure the active host origin using the following hierarchy:
      * 1. `window.location.ancestorOrigins[0]` (when supported) — the browser's
@@ -845,6 +1026,8 @@ declare class PartnerConnect {
      * continue to use the same active origin.
      */
     private static readonly SESSION_STORAGE_KEY;
+    /** Persisted so the parameter only has to be typed once per tab. */
+    private static readonly PUBLISH_SESSION_STORAGE_KEY;
     /**
      * Read `window.location.ancestorOrigins[0]` without throwing if the
      * property is unavailable (Firefox) or the list is empty (top-level
@@ -853,6 +1036,7 @@ declare class PartnerConnect {
     private readAncestorOrigin;
     private configureActiveOrigin;
     private persistOverride;
+    private persistPublishOverride;
     private isOriginNativeApp;
     /**
      * Internal placeholder substituted in for `*` so that `new URL(...)` can
@@ -928,12 +1112,48 @@ declare class PartnerConnect {
      * ```
      */
     requestIdentity(): Promise<IdentityResponse>;
+    /**
+     * Validate an inline credential template entirely offline.
+     *
+     * This performs the same local checks that {@link sendCredential} runs for
+     * inline templates before posting any message to LearnCard.
+     *
+     * @param template - Inline credential template to validate
+     * @param templateData - Optional runtime variable values to validate against the compiled manifest
+     * @returns Validation status plus path-based errors suitable for UI display
+     *
+     * @example
+     * ```typescript
+     * const result = learnCard.validateCredentialTemplate(
+     *   {
+     *     name: 'Completed {{courseName}}',
+     *     description: 'Awarded for finishing {{courseName}}.',
+     *     achievementType: 'Course',
+     *     criteria: { narrative: 'Finished all modules' }
+     *   },
+     *   { courseName: 'Intro to Baking' }
+     * );
+     *
+     * if (!result.valid) {
+     *   console.error(result.errors.map(error => `${error.path}: ${error.message}`).join('\n'));
+     * }
+     * ```
+     */
+    validateCredentialTemplate(template: InlineCredentialTemplate, templateData?: Record<string, unknown>): {
+        valid: boolean;
+        errors: InlineTemplateValidationError[];
+    };
+    /**
+     * Compile and optionally render an inline credential template entirely offline.
+     */
+    previewCompiledTemplate(template: InlineCredentialTemplate, templateData?: Record<string, unknown>): PreviewCompiledTemplateResult;
     /**
      * Send a credential to the user's LearnCard wallet
      *
      * Supports two modes:
      * 1. **Raw credential**: Pass a full verifiable credential object
      * 2. **Template-based**: Pass `{ templateAlias, templateData }` to issue from a pre-configured boost template
+     * 3. **Inline template**: Pass `{ alias, template, templateData }` to issue from a zero-config inline template
      *
      * @param input - Either a verifiable credential or a template-based input
      * @returns Promise resolving to credential response
@@ -956,8 +1176,22 @@ declare class PartnerConnect {
      * });
      * console.log('Credential URI:', response.credentialUri);
      * ```
+     *
+     * @example Inline template (zero-config)
+     * ```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' }
+     * });
+     * ```
      */
-    sendCredential(input: unknown | TemplateCredentialInput): Promise<SendCredentialResponse | TemplateCredentialResponse>;
+    sendCredential(input: SendCredentialInput): Promise<SendCredentialResponse | TemplateCredentialResponse>;
     /**
      * Check whether the current user already has a credential from a given boost template.
      * This is a silent, non-interactive status check for installed app integrations.
@@ -1073,9 +1307,12 @@ declare class PartnerConnect {
      */
     askCredentialSpecific(credentialId: string): Promise<CredentialSpecificResponse>;
     /**
-     * Request user consent for permissions
+     * Request user consent for permissions.
      *
-     * @param contractUri - URI of the consent contract (optional for App Store apps with configured contracts)
+     * Pass either a pre-created consent contract URI, or a declarative consent
+     * request and let LearnCard resolve or create the backing contract.
+     *
+     * @param requestOrContractUri - Consent scope request or explicit contract URI
      * @param options - Additional options including redirect behavior
      * @returns Promise resolving to consent response
      *
@@ -1083,21 +1320,16 @@ declare class PartnerConnect {
      * ```typescript
      * // With explicit contract URI (for external/non-app store integrations)
      * const response = await learnCard.requestConsent('lc:network:network.learncard.com/trpc:contract:abc123');
-     * if (response.granted) {
-     *   console.log('User granted consent');
-     * }
      *
-     * // Without contract URI (uses app's configured contract from integration)
-     * // This works for App Store apps that have configured a contract in their integration
-     * const response = await learnCard.requestConsent();
-     * if (response.granted) {
-     *   console.log('User granted consent using listing contract');
-     * }
-     *
-     * // With redirect - redirects to contract's redirectUrl with VP in URL params
-     * const response = await learnCard.requestConsent(undefined, { redirect: true });
+     * // Declarative scopes (LearnCard upserts the contract automatically)
+     * const { granted } = await learnCard.requestConsent({
+     *   read: { credentialCategories: ['Achievement', 'Skill'], personalFields: ['name'] },
+     *   write: { credentialCategories: ['Achievement'] },
+     *   reason: 'Personalize your training plan',
+     * });
      * ```
      */
+    requestConsent(request: ConsentRequest, options?: RequestConsentOptions): Promise<ConsentResponse>;
     requestConsent(contractUri?: string, options?: RequestConsentOptions): Promise<ConsentResponse>;
     /**
      * Initiate a template-based credential issuance flow
@@ -1243,4 +1475,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, 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 };
+export { AppEvent, AppEventResponse, AppNotificationInput, AppNotificationResponse, CapturedManifestReadable, CheckCredentialInput, CheckCredentialResponse, CheckIssuanceStatusInput, ConsentResponse, CredentialSearchResponse, CredentialSpecificResponse, ErrorCode, GetCounterResponse, GetCountersResponse, GetTemplateRecipientsInput, IdentityResponse, IncrementCounterResponse, InlineTemplateCredentialInput, InlineTemplateSendCredentialEvent, LearnCardError, LearnerContextCacheStatus, LearnerContextRawData, LearnerContextResponse, LearnerContextTimingBreakdown, MockCredentialSeed, MockHostOptions, MockIdentitySeed, PartnerConnect, PartnerConnectError, PartnerConnectOptions, PendingRequest, PostMessageRequest, PostMessageResponse, PreviewCompiledTemplateResult, RequestConsentOptions, RequestConsentPayload, RequestLearnerContextOptions, SendAiSessionCredentialInput, SendAiSessionCredentialResponse, SendCredentialEvent, SendCredentialInput, SendCredentialResponse, SummaryCredentialData, SummaryCredentialKeyword, SummaryCredentialNextStep, SummaryCredentialReflection, SummaryCredentialSkill, SyncProgress, SyncStatus, TemplateCredentialInput, TemplateCredentialResponse, TemplateIssuanceStatusResponse, TemplateIssueResponse, TemplateRecipientRecord, TemplateRecipientsResponse, VPRQuery, VerifiablePresentationRequest, createPartnerConnect, createPartnerConnect as default, isEmbedded, previewCompiledTemplate };