@learncard/partner-connect 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,383 @@
+/**
+ * LearnCard Partner Connect SDK - Type Definitions
+ */
+/**
+ * Configuration options for initializing the SDK
+ */
+interface PartnerConnectOptions {
+    /**
+     * The origin(s) of the LearnCard host
+     *
+     * This can be a single string or an array of strings to serve as a whitelist for
+     * the `lc_host_override` query parameter.
+     *
+     * **Origin Configuration Hierarchy:**
+     * 1. **Hardcoded Default**: `https://learncard.app` (security anchor)
+     * 2. **Query Parameter Override**: `?lc_host_override=https://staging.learncard.app`
+     *    - Checked against whitelist if `hostOrigin` is provided
+     *    - Used for staging/testing environments
+     * 3. **Configured Origin**: First value in array or single string value
+     *
+     * **Security Model:**
+     * - The SDK enforces STRICT origin validation
+     * - Incoming messages must EXACTLY match the active host origin
+     * - Prevents origin spoofing: even if malicious query param is added,
+     *   messages from unauthorized origins are rejected
+     *
+     * **Examples:**
+     *
+     * Single origin (production):
+     * ```typescript
+     * hostOrigin: 'https://learncard.app'
+     * // Uses: https://learncard.app
+     * // Override: ?lc_host_override=https://staging.learncard.app (not validated)
+     * ```
+     *
+     * Multiple origins (whitelist for staging):
+     * ```typescript
+     * hostOrigin: ['https://learncard.app', 'https://staging.learncard.app']
+     * // Default: https://learncard.app
+     * // Override: ?lc_host_override=https://staging.learncard.app (validated)
+     * // Invalid: ?lc_host_override=https://evil.com (rejected)
+     * ```
+     *
+     * @default 'https://learncard.app'
+     */
+    hostOrigin?: string | string[];
+    /**
+     * Whether to allow native app origins (default: true)
+     *
+     * @default true
+     */
+    allowNativeAppOrigins?: boolean;
+    /**
+     * Protocol identifier (default: 'LEARNCARD_V1')
+     */
+    protocol?: string;
+    /**
+     * Request timeout in milliseconds (default: 30000)
+     */
+    requestTimeout?: number;
+}
+/**
+ * Identity information returned from REQUEST_IDENTITY
+ */
+interface IdentityResponse {
+    token: string;
+    user: {
+        did: string;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Response from SEND_CREDENTIAL action
+ */
+interface SendCredentialResponse {
+    credentialId: string;
+    [key: string]: unknown;
+}
+/**
+ * Verifiable Presentation Request Query types
+ */
+type VPRQuery = {
+    type: 'QueryByTitle';
+    credentialQuery: {
+        reason?: string;
+        title: string;
+    };
+} | {
+    type: 'QueryByExample';
+    credentialQuery: unknown;
+};
+/**
+ * Verifiable Presentation Request structure
+ */
+interface VerifiablePresentationRequest {
+    query: VPRQuery[];
+    challenge: string;
+    domain: string;
+}
+/**
+ * Response from ASK_CREDENTIAL_SEARCH action
+ */
+interface CredentialSearchResponse {
+    verifiablePresentation?: {
+        verifiableCredential: unknown[];
+        [key: string]: unknown;
+    };
+}
+/**
+ * Response from ASK_CREDENTIAL_SPECIFIC action
+ */
+interface CredentialSpecificResponse {
+    credential?: unknown;
+}
+/**
+ * Response from REQUEST_CONSENT action
+ */
+interface ConsentResponse {
+    granted: boolean;
+    [key: string]: unknown;
+}
+/**
+ * Response from INITIATE_TEMPLATE_ISSUE action
+ */
+interface TemplateIssueResponse {
+    issued: boolean;
+    [key: string]: unknown;
+}
+/**
+ * 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' | string;
+/**
+ * Error object returned when a request fails
+ */
+interface LearnCardError {
+    code: ErrorCode;
+    message: string;
+}
+/**
+ * Internal message structure sent via postMessage
+ */
+interface PostMessageRequest {
+    protocol: string;
+    action: string;
+    requestId: string;
+    payload?: unknown;
+}
+/**
+ * Internal message structure received via postMessage
+ */
+interface PostMessageResponse {
+    protocol: string;
+    requestId: string;
+    type: 'SUCCESS' | 'ERROR';
+    data?: unknown;
+    error?: LearnCardError;
+}
+/**
+ * Pending request tracking structure
+ */
+interface PendingRequest {
+    resolve: (value: unknown) => void;
+    reject: (error: LearnCardError) => void;
+    timeoutId: NodeJS.Timeout;
+}
+
+/**
+ * LearnCard Partner Connect SDK
+ *
+ * A Promise-based JavaScript utility for managing cross-origin message communication
+ * between partner apps and the LearnCard host application.
+ *
+ * @example
+ * ```typescript
+ * import { createPartnerConnect } from '@learncard/partner-connect';
+ *
+ * const learnCard = createPartnerConnect({
+ *   hostOrigin: 'https://learncard.app'
+ * });
+ *
+ * // Request user identity (SSO)
+ * const identity = await learnCard.requestIdentity();
+ * console.log('User DID:', identity.user.did);
+ * ```
+ */
+
+/**
+ * LearnCard Partner Connect SDK class
+ */
+declare class PartnerConnect {
+    /** Default host origin (security anchor) */
+    static readonly DEFAULT_HOST_ORIGIN = "https://learncard.app";
+    private hostOrigins;
+    private activeHostOrigin;
+    private allowNativeAppOrigins;
+    private protocol;
+    private requestTimeout;
+    private pendingRequests;
+    private messageListener;
+    private isInitialized;
+    constructor(options?: PartnerConnectOptions);
+    /**
+     * Configure the active host origin using the following hierarchy:
+     * 1. Check for `lc_host_override` query parameter (for staging/testing)
+     * 2. Fall back to first configured origin
+     * 3. Fall back to DEFAULT_HOST_ORIGIN
+     *
+     * This origin will be used for all outgoing messages and incoming message validation.
+     */
+    private configureActiveOrigin;
+    private isOriginNativeApp;
+    /**
+     * Check if an origin is in the configured whitelist
+     */
+    private isOriginInWhitelist;
+    /**
+     * Check if an event origin is valid against the active host origin
+     *
+     * Security Rule: Incoming messages must exactly match the active host origin.
+     * This prevents malicious actors from spoofing origins via query parameters.
+     *
+     * @param eventOrigin - The origin from the MessageEvent
+     * @returns true if the origin is valid
+     */
+    private isValidOrigin;
+    /**
+     * Set up the central message listener to handle responses from the LearnCard host
+     */
+    private setupMessageListener;
+    /**
+     * Generate a unique request ID
+     */
+    private generateRequestId;
+    /**
+     * Send a message to the parent window and return a Promise
+     */
+    private sendMessage;
+    /**
+     * Request user identity (Single Sign-On)
+     *
+     * @returns Promise resolving to user identity including DID and JWT token
+     * @throws {LearnCardError} When user is not authenticated or request fails
+     *
+     * @example
+     * ```typescript
+     * const identity = await learnCard.requestIdentity();
+     * console.log('User DID:', identity.user.did);
+     * console.log('JWT Token:', identity.token);
+     * ```
+     */
+    requestIdentity(): Promise<IdentityResponse>;
+    /**
+     * Send a credential to the user's LearnCard wallet
+     *
+     * @param credential - The verifiable credential to send
+     * @returns Promise resolving to credential ID
+     *
+     * @example
+     * ```typescript
+     * const response = await learnCard.sendCredential({
+     *   '@context': ['https://www.w3.org/2018/credentials/v1'],
+     *   type: ['VerifiableCredential'],
+     *   credentialSubject: { id: 'did:example:123' }
+     * });
+     * console.log('Credential ID:', response.credentialId);
+     * ```
+     */
+    sendCredential(credential: unknown): Promise<SendCredentialResponse>;
+    /**
+     * Launch a feature in the LearnCard host application
+     *
+     * @param featurePath - Path to the feature (e.g., '/ai/topics')
+     * @param initialPrompt - Optional initial prompt or data
+     *
+     * @example
+     * ```typescript
+     * await learnCard.launchFeature(
+     *   '/ai/topics?shortCircuitStep=newTopic',
+     *   'Help me understand cryptography'
+     * );
+     * ```
+     */
+    launchFeature(featurePath: string, initialPrompt?: string): Promise<void>;
+    /**
+     * Request credentials from the user's wallet using a query
+     *
+     * @param verifiablePresentationRequest - VPR with query criteria
+     * @returns Promise resolving to verifiable presentation
+     *
+     * @example
+     * ```typescript
+     * const response = await learnCard.askCredentialSearch({
+     *   query: [{
+     *     type: 'QueryByTitle',
+     *     credentialQuery: {
+     *       reason: 'We need to verify your skills',
+     *       title: 'JavaScript Expert'
+     *     }
+     *   }],
+     *   challenge: 'challenge-123',
+     *   domain: window.location.hostname
+     * });
+     *
+     * if (response.verifiablePresentation) {
+     *   console.log('Received credentials:', response.verifiablePresentation.verifiableCredential);
+     * }
+     * ```
+     */
+    askCredentialSearch(verifiablePresentationRequest: VerifiablePresentationRequest): Promise<CredentialSearchResponse>;
+    /**
+     * Request a specific credential by ID
+     *
+     * @param credentialId - The ID of the credential to request
+     * @returns Promise resolving to the credential
+     *
+     * @example
+     * ```typescript
+     * const response = await learnCard.askCredentialSpecific('credential-id-123');
+     * if (response.credential) {
+     *   console.log('Received credential:', response.credential);
+     * }
+     * ```
+     */
+    askCredentialSpecific(credentialId: string): Promise<CredentialSpecificResponse>;
+    /**
+     * Request user consent for permissions
+     *
+     * @param contractUri - URI of the consent contract
+     * @returns Promise resolving to consent response
+     *
+     * @example
+     * ```typescript
+     * const response = await learnCard.requestConsent('lc:network:network.learncard.com/trpc:contract:abc123');
+     * if (response.granted) {
+     *   console.log('User granted consent');
+     * }
+     * ```
+     */
+    requestConsent(contractUri: string): Promise<ConsentResponse>;
+    /**
+     * Initiate a template-based credential issuance flow
+     *
+     * @param templateId - ID of the template/boost to issue
+     * @param draftRecipients - Optional array of recipient DIDs
+     * @returns Promise resolving to template issue response
+     *
+     * @example
+     * ```typescript
+     * const response = await learnCard.initiateTemplateIssue(
+     *   'lc:network:network.learncard.com/trpc:boost:xyz789',
+     *   ['did:key:abc', 'did:key:def']
+     * );
+     *
+     * if (response.issued) {
+     *   console.log('Template issued successfully');
+     * }
+     * ```
+     */
+    initiateTemplateIssue(templateId: string, draftRecipients?: string[]): Promise<TemplateIssueResponse>;
+    /**
+     * Clean up the SDK and remove event listeners
+     */
+    destroy(): void;
+}
+/**
+ * Factory function to create a PartnerConnect instance
+ *
+ * @param options - Configuration options
+ * @returns PartnerConnect instance
+ *
+ * @example
+ * ```typescript
+ * const learnCard = createPartnerConnect({
+ *   hostOrigin: 'https://learncard.app',
+ *   protocol: 'LEARNCARD_V1',
+ *   requestTimeout: 30000
+ * });
+ * ```
+ */
+declare function createPartnerConnect(options: PartnerConnectOptions): PartnerConnect;
+
+export { ConsentResponse, CredentialSearchResponse, CredentialSpecificResponse, ErrorCode, IdentityResponse, LearnCardError, PartnerConnect, PartnerConnectOptions, PendingRequest, PostMessageRequest, PostMessageResponse, SendCredentialResponse, TemplateIssueResponse, VPRQuery, VerifiablePresentationRequest, createPartnerConnect, createPartnerConnect as default };

package/dist/partner-connect.esm.js

@@ -0,0 +1,324 @@
+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 _PartnerConnect = class _PartnerConnect {
+  constructor(options) {
+    __publicField(this, "hostOrigins", ["https://learncard.app"]);
+    __publicField(this, "activeHostOrigin", "https://learncard.app");
+    __publicField(this, "allowNativeAppOrigins", true);
+    __publicField(this, "protocol", "LEARNCARD_V1");
+    __publicField(this, "requestTimeout", 3e4);
+    __publicField(this, "pendingRequests");
+    __publicField(this, "messageListener", null);
+    __publicField(this, "isInitialized", false);
+    var _a;
+    const hostOrigin = (options == null ? void 0 : options.hostOrigin) || _PartnerConnect.DEFAULT_HOST_ORIGIN;
+    this.hostOrigins = Array.isArray(hostOrigin) ? hostOrigin : [hostOrigin];
+    this.protocol = (options == null ? void 0 : options.protocol) || "LEARNCARD_V1";
+    this.requestTimeout = (options == null ? void 0 : options.requestTimeout) || 3e4;
+    this.allowNativeAppOrigins = (_a = options == null ? void 0 : options.allowNativeAppOrigins) != null ? _a : true;
+    this.pendingRequests = /* @__PURE__ */ new Map();
+    this.configureActiveOrigin();
+    this.setupMessageListener();
+  }
+  /**
+   * Configure the active host origin using the following hierarchy:
+   * 1. Check for `lc_host_override` query parameter (for staging/testing)
+   * 2. Fall back to first configured origin
+   * 3. Fall back to DEFAULT_HOST_ORIGIN
+   * 
+   * This origin will be used for all outgoing messages and incoming message validation.
+   */
+  configureActiveOrigin() {
+    if (typeof window === "undefined") {
+      this.activeHostOrigin = this.hostOrigins[0] || _PartnerConnect.DEFAULT_HOST_ORIGIN;
+      return;
+    }
+    try {
+      const urlParams = new URLSearchParams(window.location.search);
+      const hostOverride = urlParams.get("lc_host_override");
+      if (hostOverride) {
+        if (this.hostOrigins.length > 0 && !this.isOriginInWhitelist(hostOverride)) {
+          console.warn(
+            "[LearnCard SDK] lc_host_override value is not in the configured whitelist:",
+            hostOverride,
+            "Allowed:",
+            this.hostOrigins
+          );
+          this.activeHostOrigin = this.hostOrigins[0] || _PartnerConnect.DEFAULT_HOST_ORIGIN;
+        } else {
+          this.activeHostOrigin = hostOverride;
+          console.log("[LearnCard SDK] Using lc_host_override:", hostOverride);
+        }
+      } else {
+        this.activeHostOrigin = this.hostOrigins[0] || _PartnerConnect.DEFAULT_HOST_ORIGIN;
+        console.log("[LearnCard SDK] Using configured origin:", this.activeHostOrigin);
+      }
+    } catch (error) {
+      console.error("[LearnCard SDK] Error configuring active origin:", error);
+      this.activeHostOrigin = this.hostOrigins[0] || _PartnerConnect.DEFAULT_HOST_ORIGIN;
+    }
+  }
+  isOriginNativeApp(origin) {
+    return origin.startsWith("capacitor://") || origin.startsWith("ionic://") || origin.startsWith("https://localhost") || origin.startsWith("http://localhost") || origin.startsWith("http://127.0.0.1") || origin.startsWith("http://192.168.1.164");
+  }
+  /**
+   * Check if an origin is in the configured whitelist
+   */
+  isOriginInWhitelist(origin) {
+    return this.hostOrigins.includes(origin) || this.allowNativeAppOrigins && this.isOriginNativeApp(origin);
+  }
+  /**
+   * Check if an event origin is valid against the active host origin
+   * 
+   * Security Rule: Incoming messages must exactly match the active host origin.
+   * This prevents malicious actors from spoofing origins via query parameters.
+   * 
+   * @param eventOrigin - The origin from the MessageEvent
+   * @returns true if the origin is valid
+   */
+  isValidOrigin(eventOrigin) {
+    return eventOrigin === this.activeHostOrigin;
+  }
+  /**
+   * Set up the central message listener to handle responses from the LearnCard host
+   */
+  setupMessageListener() {
+    if (typeof window === "undefined") {
+      throw new Error("PartnerConnect SDK can only be used in a browser environment");
+    }
+    this.messageListener = (event) => {
+      if (!this.isValidOrigin(event.origin)) {
+        return;
+      }
+      const data = event.data;
+      if (data.protocol !== this.protocol || !data.requestId) {
+        return;
+      }
+      const pending = this.pendingRequests.get(data.requestId);
+      if (!pending) {
+        return;
+      }
+      clearTimeout(pending.timeoutId);
+      this.pendingRequests.delete(data.requestId);
+      if (data.type === "SUCCESS") {
+        pending.resolve(data.data);
+      } else if (data.type === "ERROR") {
+        pending.reject(data.error || { code: "UNKNOWN_ERROR", message: "An unknown error occurred" });
+      }
+    };
+    window.addEventListener("message", this.messageListener);
+    this.isInitialized = true;
+  }
+  /**
+   * Generate a unique request ID
+   */
+  generateRequestId(action) {
+    return `${action}-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+  }
+  /**
+   * Send a message to the parent window and return a Promise
+   */
+  sendMessage(action, payload) {
+    if (!this.isInitialized) {
+      return Promise.reject({
+        code: "SDK_NOT_INITIALIZED",
+        message: "SDK is not initialized"
+      });
+    }
+    return new Promise((resolve, reject) => {
+      const requestId = this.generateRequestId(action);
+      const timeoutId = setTimeout(() => {
+        if (this.pendingRequests.has(requestId)) {
+          this.pendingRequests.delete(requestId);
+          reject({
+            code: "LC_TIMEOUT",
+            message: `Request ${action} timed out after ${this.requestTimeout}ms`
+          });
+        }
+      }, this.requestTimeout);
+      this.pendingRequests.set(requestId, {
+        resolve,
+        reject,
+        timeoutId
+      });
+      const message = {
+        protocol: this.protocol,
+        action,
+        requestId,
+        payload
+      };
+      window.parent.postMessage(message, this.activeHostOrigin);
+    });
+  }
+  /**
+   * Request user identity (Single Sign-On)
+   * 
+   * @returns Promise resolving to user identity including DID and JWT token
+   * @throws {LearnCardError} When user is not authenticated or request fails
+   * 
+   * @example
+   * ```typescript
+   * const identity = await learnCard.requestIdentity();
+   * console.log('User DID:', identity.user.did);
+   * console.log('JWT Token:', identity.token);
+   * ```
+   */
+  requestIdentity() {
+    return this.sendMessage("REQUEST_IDENTITY", { challenge: `${Date.now()}-${Math.random().toString(36).substring(2, 9)}` });
+  }
+  /**
+   * Send a credential to the user's LearnCard wallet
+   * 
+   * @param credential - The verifiable credential to send
+   * @returns Promise resolving to credential ID
+   * 
+   * @example
+   * ```typescript
+   * const response = await learnCard.sendCredential({
+   *   '@context': ['https://www.w3.org/2018/credentials/v1'],
+   *   type: ['VerifiableCredential'],
+   *   credentialSubject: { id: 'did:example:123' }
+   * });
+   * console.log('Credential ID:', response.credentialId);
+   * ```
+   */
+  sendCredential(credential) {
+    return this.sendMessage("SEND_CREDENTIAL", { credential });
+  }
+  /**
+   * Launch a feature in the LearnCard host application
+   * 
+   * @param featurePath - Path to the feature (e.g., '/ai/topics')
+   * @param initialPrompt - Optional initial prompt or data
+   * 
+   * @example
+   * ```typescript
+   * await learnCard.launchFeature(
+   *   '/ai/topics?shortCircuitStep=newTopic',
+   *   'Help me understand cryptography'
+   * );
+   * ```
+   */
+  launchFeature(featurePath, initialPrompt) {
+    return this.sendMessage("LAUNCH_FEATURE", { featurePath, initialPrompt });
+  }
+  /**
+   * Request credentials from the user's wallet using a query
+   * 
+   * @param verifiablePresentationRequest - VPR with query criteria
+   * @returns Promise resolving to verifiable presentation
+   * 
+   * @example
+   * ```typescript
+   * const response = await learnCard.askCredentialSearch({
+   *   query: [{
+   *     type: 'QueryByTitle',
+   *     credentialQuery: {
+   *       reason: 'We need to verify your skills',
+   *       title: 'JavaScript Expert'
+   *     }
+   *   }],
+   *   challenge: 'challenge-123',
+   *   domain: window.location.hostname
+   * });
+   * 
+   * if (response.verifiablePresentation) {
+   *   console.log('Received credentials:', response.verifiablePresentation.verifiableCredential);
+   * }
+   * ```
+   */
+  askCredentialSearch(verifiablePresentationRequest) {
+    return this.sendMessage("ASK_CREDENTIAL_SEARCH", {
+      verifiablePresentationRequest
+    });
+  }
+  /**
+   * Request a specific credential by ID
+   * 
+   * @param credentialId - The ID of the credential to request
+   * @returns Promise resolving to the credential
+   * 
+   * @example
+   * ```typescript
+   * const response = await learnCard.askCredentialSpecific('credential-id-123');
+   * if (response.credential) {
+   *   console.log('Received credential:', response.credential);
+   * }
+   * ```
+   */
+  askCredentialSpecific(credentialId) {
+    return this.sendMessage("ASK_CREDENTIAL_SPECIFIC", {
+      credentialId
+    });
+  }
+  /**
+   * Request user consent for permissions
+   * 
+   * @param contractUri - URI of the consent contract
+   * @returns Promise resolving to consent response
+   * 
+   * @example
+   * ```typescript
+   * const response = await learnCard.requestConsent('lc:network:network.learncard.com/trpc:contract:abc123');
+   * if (response.granted) {
+   *   console.log('User granted consent');
+   * }
+   * ```
+   */
+  requestConsent(contractUri) {
+    return this.sendMessage("REQUEST_CONSENT", { contractUri });
+  }
+  /**
+   * Initiate a template-based credential issuance flow
+   * 
+   * @param templateId - ID of the template/boost to issue
+   * @param draftRecipients - Optional array of recipient DIDs
+   * @returns Promise resolving to template issue response
+   * 
+   * @example
+   * ```typescript
+   * const response = await learnCard.initiateTemplateIssue(
+   *   'lc:network:network.learncard.com/trpc:boost:xyz789',
+   *   ['did:key:abc', 'did:key:def']
+   * );
+   * 
+   * if (response.issued) {
+   *   console.log('Template issued successfully');
+   * }
+   * ```
+   */
+  initiateTemplateIssue(templateId, draftRecipients) {
+    return this.sendMessage("INITIATE_TEMPLATE_ISSUE", {
+      templateId,
+      draftRecipients: draftRecipients || []
+    });
+  }
+  /**
+   * Clean up the SDK and remove event listeners
+   */
+  destroy() {
+    if (this.messageListener) {
+      window.removeEventListener("message", this.messageListener);
+      this.messageListener = null;
+    }
+    for (const [requestId, pending] of this.pendingRequests.entries()) {
+      clearTimeout(pending.timeoutId);
+      pending.reject({
+        code: "SDK_DESTROYED",
+        message: "SDK was destroyed before request completed"
+      });
+    }
+    this.pendingRequests.clear();
+    this.isInitialized = false;
+  }
+};
+/** Default host origin (security anchor) */
+__publicField(_PartnerConnect, "DEFAULT_HOST_ORIGIN", "https://learncard.app");
+let PartnerConnect = _PartnerConnect;
+function createPartnerConnect(options) {
+  return new PartnerConnect(options);
+}
+
+export { PartnerConnect, createPartnerConnect, createPartnerConnect as default };
+//# sourceMappingURL=partner-connect.esm.js.map