@learncard/partner-connect 0.2.14 → 0.3.0

package/dist/partner-connect.js

@@ -2,6 +2,39 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
+var __defProp$1 = Object.defineProperty;
+var __defNormalProp$1 = (obj, key, value) => key in obj ? __defProp$1(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField$1 = (obj, key, value) => __defNormalProp$1(obj, typeof key !== "symbol" ? key + "" : key, value);
+class PartnerConnectError extends Error {
+  constructor(code, message) {
+    super(message);
+    __publicField$1(this, "code");
+    this.name = "PartnerConnectError";
+    this.code = code;
+    Object.setPrototypeOf(this, PartnerConnectError.prototype);
+  }
+  /**
+   * Wrap any incoming `LearnCardError`-shaped value into a `PartnerConnectError`.
+   * Returns the value unchanged if it is already an instance.
+   *
+   * Used internally at every reject site so callers always receive a typed
+   * `PartnerConnectError`, regardless of whether the failure originated from
+   * the host (over postMessage), an SDK timeout, or `destroy()`.
+   */
+  static from(input) {
+    if (input instanceof PartnerConnectError) return input;
+    if (input && typeof input === "object" && "code" in input && typeof input.code === "string") {
+      const candidate = input;
+      const message = typeof candidate.message === "string" ? candidate.message : "Partner Connect request failed";
+      return new PartnerConnectError(candidate.code, message);
+    }
+    return new PartnerConnectError(
+      "UNKNOWN_ERROR",
+      input instanceof Error ? input.message : "An unknown error occurred"
+    );
+  }
+}
+
 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);
@@ -15,62 +48,160 @@ const _PartnerConnect = class _PartnerConnect {
     __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];
+    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];
+    const disableDefaults = (options == null ? void 0 : options.disableDefaultTenants) === true;
+    const merged = disableDefaults ? [...configured] : [...configured, ..._PartnerConnect.DEFAULT_TRUSTED_TENANTS];
+    this.hostOrigins = Array.from(new Set(merged));
     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.allowNativeAppOrigins = (_b = options == null ? void 0 : options.allowNativeAppOrigins) != null ? _b : 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.
+   * Read `window.location.ancestorOrigins[0]` without throwing if the
+   * property is unavailable (Firefox) or the list is empty (top-level
+   * context, e.g. running outside of an iframe).
    */
+  readAncestorOrigin() {
+    if (typeof window === "undefined") return null;
+    try {
+      const ancestors = window.location.ancestorOrigins;
+      if (ancestors && ancestors.length > 0) {
+        const parent = ancestors[0];
+        if (typeof parent === "string" && parent.length > 0) {
+          return parent;
+        }
+      }
+    } catch {
+    }
+    return null;
+  }
   configureActiveOrigin() {
     if (typeof window === "undefined") {
       this.activeHostOrigin = this.hostOrigins[0] || _PartnerConnect.DEFAULT_HOST_ORIGIN;
       return;
     }
     try {
+      const ancestorOrigin = this.readAncestorOrigin();
       const urlParams = new URLSearchParams(window.location.search);
       const hostOverride = urlParams.get("lc_host_override");
-      if (hostOverride) {
-        if (this.hostOrigins.length > 0 && !this.isOriginInWhitelist(hostOverride)) {
+      if (ancestorOrigin && this.isOriginInWhitelist(ancestorOrigin)) {
+        if (hostOverride && hostOverride !== ancestorOrigin) {
           console.warn(
-            "[LearnCard SDK] lc_host_override value is not in the configured whitelist:",
-            hostOverride,
-            "Allowed:",
-            this.hostOrigins
+            "[LearnCard SDK] lc_host_override does not match the real parent origin; preferring parent.",
+            { override: hostOverride, parent: ancestorOrigin }
           );
-          this.activeHostOrigin = this.hostOrigins[0] || _PartnerConnect.DEFAULT_HOST_ORIGIN;
-        } else {
+        }
+        this.activeHostOrigin = ancestorOrigin;
+        this.persistOverride(ancestorOrigin);
+        console.log("[LearnCard SDK] Using parent origin:", ancestorOrigin);
+        return;
+      }
+      if (hostOverride) {
+        if (this.isOriginInWhitelist(hostOverride)) {
           this.activeHostOrigin = hostOverride;
+          this.persistOverride(hostOverride);
           console.log("[LearnCard SDK] Using lc_host_override:", hostOverride);
+          return;
         }
-      } else {
-        this.activeHostOrigin = this.hostOrigins[0] || _PartnerConnect.DEFAULT_HOST_ORIGIN;
-        console.log("[LearnCard SDK] Using configured origin:", this.activeHostOrigin);
+        console.warn(
+          "[LearnCard SDK] lc_host_override value is not in the configured whitelist:",
+          hostOverride,
+          "Allowed:",
+          this.hostOrigins
+        );
+      }
+      let storedOverride = null;
+      try {
+        storedOverride = sessionStorage.getItem(_PartnerConnect.SESSION_STORAGE_KEY);
+      } catch {
       }
+      if (storedOverride && this.isOriginInWhitelist(storedOverride)) {
+        this.activeHostOrigin = storedOverride;
+        console.log("[LearnCard SDK] Using stored lc_host_override:", storedOverride);
+        return;
+      }
+      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;
     }
   }
+  persistOverride(origin) {
+    try {
+      sessionStorage.setItem(_PartnerConnect.SESSION_STORAGE_KEY, origin);
+    } catch {
+    }
+  }
   isOriginNativeApp(origin) {
     return origin.startsWith("capacitor://") || origin.startsWith("ionic://") || origin.startsWith("https://localhost") || origin.startsWith("http://localhost") || origin.startsWith("http://127.0.0.1");
   }
   /**
-   * Check if an origin is in the configured whitelist
+   * Check whether a candidate origin matches a configured whitelist entry.
+   *
+   * Supports exact matches and wildcard patterns. A wildcard entry has the
+   * form `<protocol>://*.<domain>` and matches any origin with the same
+   * protocol, same port, and a host ending in `.<domain>` with at least
+   * one non-empty DNS label in place of the `*`.
+   *
+   * Examples with pattern `https://*.learncard.app`:
+   * - `https://staging.learncard.app`      → match
+   * - `https://pr-1.preview.learncard.app` → match
+   * - `https://learncard.app`              → no match (no subdomain)
+   * - `http://staging.learncard.app`       → no match (protocol mismatch)
+   * - `https://learncard.app.attacker.com` → no match (suffix mismatch)
+   *
+   * Exposed as a public static so it can be unit-tested directly without
+   * standing up a full SDK instance.
+   */
+  static matchesOriginPattern(candidate, pattern) {
+    if (candidate === pattern) return true;
+    if (!pattern.includes("*")) return false;
+    let patternUrl;
+    let candidateUrl;
+    try {
+      patternUrl = new URL(
+        pattern.replace(
+          _PartnerConnect.WILDCARD_REGEX,
+          _PartnerConnect.WILDCARD_PLACEHOLDER
+        )
+      );
+      candidateUrl = new URL(candidate);
+    } catch {
+      return false;
+    }
+    if (patternUrl.protocol !== candidateUrl.protocol) return false;
+    if (patternUrl.port !== candidateUrl.port) return false;
+    const patternHost = patternUrl.hostname;
+    const candidateHost = candidateUrl.hostname;
+    if (!patternHost.startsWith(_PartnerConnect.WILDCARD_LEADING_PREFIX)) return false;
+    const patternSuffix = patternHost.slice(_PartnerConnect.WILDCARD_LEADING_PREFIX.length);
+    if (patternSuffix.length === 0) return false;
+    if (patternSuffix.includes(_PartnerConnect.WILDCARD_PLACEHOLDER)) return false;
+    const required = "." + patternSuffix;
+    if (!candidateHost.endsWith(required)) return false;
+    const prefix = candidateHost.slice(0, candidateHost.length - required.length);
+    if (prefix.length === 0) return false;
+    if (prefix.startsWith(".") || prefix.endsWith(".")) return false;
+    if (prefix.split(".").some((label) => label.length === 0)) return false;
+    return true;
+  }
+  /**
+   * Check if an origin is in the effective whitelist (exact origins +
+   * wildcard patterns + optional native-app origins).
    */
   isOriginInWhitelist(origin) {
-    return this.hostOrigins.includes(origin) || this.allowNativeAppOrigins && this.isOriginNativeApp(origin);
+    if (!origin) return false;
+    for (const entry of this.hostOrigins) {
+      if (_PartnerConnect.matchesOriginPattern(origin, entry)) return true;
+    }
+    if (this.allowNativeAppOrigins && this.isOriginNativeApp(origin)) return true;
+    return false;
   }
   /**
    * Check if an event origin is valid against the active host origin
@@ -109,7 +240,12 @@ const _PartnerConnect = class _PartnerConnect {
         pending.resolve(data.data);
       } else if (data.type === "ERROR") {
         pending.reject(
-          data.error || { code: "UNKNOWN_ERROR", message: "An unknown error occurred" }
+          PartnerConnectError.from(
+            data.error || {
+              code: "UNKNOWN_ERROR",
+              message: "An unknown error occurred"
+            }
+          )
         );
       }
     };
@@ -127,20 +263,21 @@ const _PartnerConnect = class _PartnerConnect {
    */
   sendMessage(action, payload) {
     if (!this.isInitialized) {
-      return Promise.reject({
-        code: "SDK_NOT_INITIALIZED",
-        message: "SDK is not initialized"
-      });
+      return Promise.reject(
+        new PartnerConnectError("SDK_NOT_INITIALIZED", "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`
-          });
+          reject(
+            new PartnerConnectError(
+              "LC_TIMEOUT",
+              `Request ${action} timed out after ${this.requestTimeout}ms`
+            )
+          );
         }
       }, this.requestTimeout);
       this.pendingRequests.set(requestId, {
@@ -358,22 +495,27 @@ const _PartnerConnect = class _PartnerConnect {
   /**
    * Request user consent for permissions
    *
-   * @param contractUri - URI of the consent contract
+   * @param contractUri - URI of the consent contract (optional for App Store apps with configured contracts)
+   * @param options - Additional options including redirect behavior
    * @returns Promise resolving to consent response
    *
    * @example
    * ```typescript
-   * // Without redirect (default) - returns VP in response if app owns the contract
+   * // 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');
-   *   if (response.vp) {
-   *     console.log('VP:', response.vp);
-   *   }
+   * }
+   *
+   * // 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('lc:network:network.learncard.com/trpc:contract:abc123', { redirect: true });
+   * const response = await learnCard.requestConsent(undefined, { redirect: true });
    * ```
    */
   requestConsent(contractUri, options = {}) {
@@ -408,6 +550,45 @@ const _PartnerConnect = class _PartnerConnect {
       draftRecipients: draftRecipients || []
     });
   }
+  /**
+   * Request comprehensive learner context for AI tutoring systems.
+   *
+   * This method retrieves the user's credentials and personal data,
+   * then formats them into an LLM-ready prompt that can be injected directly into
+   * an AI system prompt.
+   *
+   * @param options - Configuration options for what data to include and how to format it
+   * @returns Promise resolving to learner context with prompt and optional raw data
+   *
+   * @example
+   * ```typescript
+   * // Get LLM-ready prompt with credentials and personal data
+   * const context = await learnCard.requestLearnerContext({
+   *   includeCredentials: true,
+   *   includePersonalData: true,
+   *   format: 'prompt',
+   *   instructions: 'Focus on technical skills and certifications',
+   *   detailLevel: 'expanded'
+   * });
+   *
+   * // Use in AI system prompt
+   * const systemPrompt = `You are a helpful tutor. ${context.prompt}`;
+   *
+   * // Access structured data if needed
+   * console.log('User DID:', context.did);
+   * console.log('Credentials count:', context.raw?.credentials.length);
+   * ```
+   */
+  requestLearnerContext(options) {
+    var _a, _b, _c, _d;
+    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"
+    });
+  }
   /**
    * 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.
@@ -432,6 +613,62 @@ const _PartnerConnect = class _PartnerConnect {
   sendAppEvent(event) {
     return this.sendMessage("APP_EVENT", event);
   }
+  /**
+   * Create and send an AI Session credential to the user.
+   *
+   * This method manages the AI Topic → AI Session hierarchy:
+   * - Ensures an AI Topic exists for this app (creates one if needed)
+   * - Creates a new AI Session as a child of the topic
+   * - The topic appears in the user's AI Sessions page with the app's name
+   * - All sessions from this app are organized under that topic
+   *
+   * @param input - Session details including title and optional metadata
+   * @returns Promise resolving to topic and session URIs
+   */
+  sendAiSessionCredential(input) {
+    return this.sendAppEvent({
+      type: "send-ai-session-credential",
+      ...input
+    });
+  }
+  /**
+   * Send a notification to the current user from this app.
+   * The notification appears in the user's LearnCard notification inbox.
+   */
+  sendNotification(input) {
+    return this.sendAppEvent({
+      type: "send-notification",
+      ...input
+    });
+  }
+  /**
+   * Increment or decrement an app-scoped counter for the current user.
+   */
+  incrementCounter(key, amount) {
+    return this.sendAppEvent({
+      type: "increment-counter",
+      key,
+      amount
+    });
+  }
+  /**
+   * Read the current value of an app-scoped counter for the current user.
+   */
+  getCounter(key) {
+    return this.sendAppEvent({
+      type: "get-counter",
+      key
+    });
+  }
+  /**
+   * Read multiple app-scoped counters at once for the current user.
+   */
+  getCounters(keys) {
+    return this.sendAppEvent({
+      type: "get-counters",
+      ...keys ? { keys } : {}
+    });
+  }
   /**
    * Clean up the SDK and remove event listeners
    */
@@ -442,10 +679,12 @@ const _PartnerConnect = class _PartnerConnect {
     }
     for (const [requestId, pending] of this.pendingRequests.entries()) {
       clearTimeout(pending.timeoutId);
-      pending.reject({
-        code: "SDK_DESTROYED",
-        message: "SDK was destroyed before request completed"
-      });
+      pending.reject(
+        new PartnerConnectError(
+          "SDK_DESTROYED",
+          "SDK was destroyed before request completed"
+        )
+      );
     }
     this.pendingRequests.clear();
     this.isInitialized = false;
@@ -453,12 +692,57 @@ const _PartnerConnect = class _PartnerConnect {
 };
 /** Default host origin (security anchor) */
 __publicField(_PartnerConnect, "DEFAULT_HOST_ORIGIN", "https://learncard.app");
+/**
+ * Built-in list of LearnCard-managed tenant origins.
+ *
+ * These are merged with the partner app's configured `hostOrigin` whitelist
+ * unless `disableDefaultTenants: true` is passed. This lets a partner app
+ * run inside any current or future LearnCard tenant (staging, preview,
+ * VetPass, etc.) without needing a re-deploy each time a new tenant is
+ * onboarded.
+ *
+ * Patterns follow the same rules as user-supplied `hostOrigin` entries:
+ * `*` is a wildcard for one or more DNS labels in the host portion.
+ */
+__publicField(_PartnerConnect, "DEFAULT_TRUSTED_TENANTS", [
+  "https://learncard.app",
+  "https://*.learncard.app",
+  "https://*.learncard.ai",
+  "https://vetpass.app",
+  "https://*.vetpass.app"
+]);
+/**
+ * Configure the active host origin using the following hierarchy:
+ * 1. `window.location.ancestorOrigins[0]` (when supported) — the browser's
+ *    view of who our parent frame is. Cannot be forged by a malicious
+ *    `lc_host_override` query param and therefore takes precedence.
+ * 2. `?lc_host_override=<origin>` query param (for staging / cross-tenant).
+ * 3. `sessionStorage` value saved from a previously-validated override.
+ * 4. First configured origin.
+ * 5. `DEFAULT_HOST_ORIGIN`.
+ *
+ * When a valid override is found in the query parameter, it is persisted
+ * to sessionStorage so subsequent in-iframe navigations in the same tab
+ * continue to use the same active origin.
+ */
+__publicField(_PartnerConnect, "SESSION_STORAGE_KEY", "lc_host_override");
+/**
+ * Internal placeholder substituted in for `*` so that `new URL(...)` can
+ * parse a wildcard pattern. Chosen to be a syntactically-valid DNS label
+ * that cannot collide with a real hostname.
+ */
+__publicField(_PartnerConnect, "WILDCARD_PLACEHOLDER", "__lc_wildcard__");
+/** `*` (any number of occurrences) for replacement in the pattern. */
+__publicField(_PartnerConnect, "WILDCARD_REGEX", /\*/g);
+/** The required leading-label form a wildcard pattern must take. */
+__publicField(_PartnerConnect, "WILDCARD_LEADING_PREFIX", `${_PartnerConnect.WILDCARD_PLACEHOLDER}.`);
 let PartnerConnect = _PartnerConnect;
 function createPartnerConnect(options) {
   return new PartnerConnect(options);
 }
 
 exports.PartnerConnect = PartnerConnect;
+exports.PartnerConnectError = PartnerConnectError;
 exports.createPartnerConnect = createPartnerConnect;
 exports["default"] = createPartnerConnect;
 //# sourceMappingURL=partner-connect.js.map