@feelflow/ffid-sdk 5.27.0 → 5.29.0

package/dist/server/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FFIDLogger, a as FFIDError, b as FFIDCacheAdapter, c as FFIDVerifyAccessTokenOptions, d as FFIDApiResponse, e as FFIDOAuthUserInfo } from '../ffid-client-BqnzUmG7.js';
-export { f as FFIDAddMemberParams, g as FFIDAddMemberRequest, h as FFIDAddMemberResponse, i as FFIDAssignableMemberRole, j as FFIDCacheConfig, k as FFIDClient, l as FFIDConfig, m as FFIDListMembersResponse, n as FFIDMemberRole, o as FFIDOrganization, p as FFIDOrganizationMember, q as FFIDOtpSendResponse, r as FFIDOtpVerifyResponse, s as FFIDPasswordResetConfirmResponse, t as FFIDPasswordResetResponse, u as FFIDPasswordResetVerifyResponse, v as FFIDProfileCallOptions, w as FFIDProvisionMemberPlan, x as FFIDProvisionMemberPlanStatus, y as FFIDProvisionMemberResult, z as FFIDProvisionMemberStatus, A as FFIDProvisionOrganizationDryRun, B as FFIDProvisionOrganizationMemberInput, C as FFIDProvisionOrganizationOutcome, D as FFIDProvisionOrganizationParams, E as FFIDProvisionOrganizationResponse, G as FFIDProvisionUserDryRun, H as FFIDProvisionUserOutcome, I as FFIDProvisionUserParams, J as FFIDProvisionUserProfileInput, K as FFIDProvisionUserResponse, L as FFIDProvisionedOrganization, M as FFIDProvisionedUser, N as FFIDRemoveMemberResponse, O as FFIDResetSessionResponse, P as FFIDSubscription, Q as FFIDUpdateMemberRoleResponse, R as FFIDUpdateUserProfileRequest, S as FFIDUser, T as FFIDUserProfile, U as TokenData, V as TokenStore, W as createFFIDClient, X as createTokenStore } from '../ffid-client-BqnzUmG7.js';
+import { F as FFIDLogger, a as FFIDError, b as FFIDCacheAdapter, c as FFIDVerifyAccessTokenOptions, d as FFIDApiResponse, e as FFIDOAuthUserInfo, f as FFIDCatalogEnvironment, g as FFIDBillingInterval, h as FFIDTaxBehavior, i as FFIDPublishedCatalog } from '../ffid-client-DCS-MoxK.js';
+export { j as FFIDAddMemberParams, k as FFIDAddMemberRequest, l as FFIDAddMemberResponse, m as FFIDAssignableMemberRole, n as FFIDCacheConfig, o as FFIDCatalogPublication, p as FFIDCatalogPublicationStatus, q as FFIDClient, r as FFIDConfig, s as FFIDListMembersResponse, t as FFIDMemberRole, u as FFIDOrganization, v as FFIDOrganizationMember, w as FFIDOtpSendResponse, x as FFIDOtpVerifyResponse, y as FFIDPasswordResetConfirmResponse, z as FFIDPasswordResetResponse, A as FFIDPasswordResetVerifyResponse, B as FFIDProfileCallOptions, C as FFIDProvisionMemberPlan, D as FFIDProvisionMemberPlanStatus, E as FFIDProvisionMemberResult, G as FFIDProvisionMemberStatus, H as FFIDProvisionOrganizationDryRun, I as FFIDProvisionOrganizationMemberInput, J as FFIDProvisionOrganizationOutcome, K as FFIDProvisionOrganizationParams, L as FFIDProvisionOrganizationResponse, M as FFIDProvisionUserDryRun, N as FFIDProvisionUserOutcome, O as FFIDProvisionUserParams, P as FFIDProvisionUserProfileInput, Q as FFIDProvisionUserResponse, R as FFIDProvisionedOrganization, S as FFIDProvisionedUser, T as FFIDPublishedPlan, U as FFIDRemoveMemberResponse, V as FFIDResetSessionResponse, W as FFIDSubscription, X as FFIDUpdateMemberRoleResponse, Y as FFIDUpdateUserProfileRequest, Z as FFIDUser, _ as FFIDUserProfile, $ as FFID_CATALOG_ENVIRONMENTS, a0 as FFID_CATALOG_PUBLICATION_STATUSES, a1 as TokenData, a2 as TokenStore, a3 as createFFIDClient, a4 as createTokenStore } from '../ffid-client-DCS-MoxK.js';
 export { D as DEFAULT_API_BASE_URL, a as DEFAULT_OAUTH_SCOPES } from '../constants-D61jqRIO.js';
 import { z } from 'zod';
 import '../types-Cjb9J0rL.js';
@@ -389,4 +389,181 @@ declare const sessionCookies: {
  */
 declare function generateServerState(): string;
 
-export { ALL_DENIED_EXCEPT_NECESSARY, type BuildAuthorizeUrlOptions, type BuildAuthorizeUrlResult, CONSENT_COOKIE_NAME, COOKIE_VERSION, type CookieOptions, FFIDCacheAdapter, type FFIDConsentCategories, type FFIDConsentCategoryCode, type FFIDCookieStoreLike, type FFIDErrorCode, FFIDOAuthUserInfo, FFIDVerifyAccessTokenOptions, FFID_ERROR_CODES, FFID_SESSION_COOKIE_NAME, type HandleCallbackInput, type KVNamespaceLike, type ServerAuthClient, type ServerAuthConfig, type ServerSessionTokens, type ServerTokenResult, createKVCacheAdapter, createMemoryCacheAdapter, createServerAuthClient, createVerifyAccessToken, decodeConsentCookie, encodeConsentCookie, generateServerState, getFFIDConsentFromCookieHeader, getFFIDConsentFromCookies, sessionCookies };
+/**
+ * Catalog approval hash helpers (#4342 / ASDD-PRICING-002 SP4A)
+ *
+ * Shared canonicalization + SHA-256 helpers that FIX the cross-repo hash
+ * contract between FFID (publisher) and consumers (Praxis). Both sides compute
+ * hashes with these helpers and refuse new sales on any mismatch, so the
+ * canonical form below is a compatibility contract:
+ *
+ *   1. Objects serialize with keys sorted by UTF-16 code unit order,
+ *      recursively. Arrays keep their element order.
+ *   2. Serialization is `JSON.stringify`-compatible per token (string
+ *      escaping, number formatting) with NO whitespace.
+ *   3. `undefined`, non-finite numbers (NaN/±Infinity), functions, symbols,
+ *      bigints and non-plain objects (Date, Map, class instances) are
+ *      REJECTED with FFIDCatalogHashError — never silently dropped, because a
+ *      dropped key would let two semantically different payloads collide.
+ *      Only own enumerable string-keyed properties participate; symbol-keyed
+ *      properties are ignored (same as `JSON.stringify`).
+ *   4. The hash is lowercase SHA-256 hex over the UTF-8 bytes of the
+ *      canonical string (no domain-separation prefix).
+ *
+ * Changing ANY of these rules is a breaking change to published catalog
+ * verification and requires re-publishing catalogs — the fixed test vectors
+ * in `__tests__/catalog-hash.test.ts` exist to make such a change loud.
+ */
+
+/** Lowercase SHA-256 hex format shared by all catalog approval hashes */
+declare const CATALOG_HASH_PATTERN: RegExp;
+/**
+ * Thrown when a value cannot be canonicalized (or an embedded hash is
+ * malformed). Always indicates a programming error on the hashing side —
+ * never caused by end-user input.
+ */
+declare class FFIDCatalogHashError extends Error {
+    constructor(message: string);
+}
+/** JSON value accepted by the canonicalizer */
+type FFIDCanonicalJsonValue = string | number | boolean | null | FFIDCanonicalJsonValue[] | {
+    [key: string]: FFIDCanonicalJsonValue;
+};
+/**
+ * Serializes a JSON-plain value into its canonical string form (see module
+ * doc for the exact rules). Exposed so both sides can debug hash mismatches
+ * by diffing canonical strings instead of opaque digests.
+ */
+declare function canonicalizeCatalogValue(value: FFIDCanonicalJsonValue): string;
+/**
+ * Lowercase SHA-256 hex of the UTF-8 bytes of `text`.
+ *
+ * Requires Web Crypto (`globalThis.crypto.subtle`) — available by default in
+ * Node.js >= 19 (Node 18 needs `--experimental-global-webcrypto`), browsers,
+ * and edge runtimes. Throws instead of falling back to a weaker digest so a
+ * missing crypto implementation can never silently change the contract.
+ */
+declare function sha256Hex(text: string): Promise<string>;
+/** Canonicalizes `value` and returns its lowercase SHA-256 hex digest. */
+declare function hashCanonicalJson(value: FFIDCanonicalJsonValue): Promise<string>;
+/**
+ * Human-approved tax configuration snapshot hashed into
+ * `publication.taxConfigurationHash`. FFID re-computes this from its live
+ * Stripe Tax settings at paid-checkout start and refuses the session on
+ * mismatch.
+ */
+interface FFIDTaxConfiguration {
+    /** ISO 3166-1 alpha-2 country/region codes where paid sales are allowed */
+    allowedCountries: string[];
+    /** Country/region codes with completed Stripe Tax registrations */
+    stripeTaxRegistrations: string[];
+    /** Whether full billing address collection is required before paid checkout */
+    billingAddressRequired: boolean;
+    /** Stripe Product tax code per plan code (e.g. `txcd_10000000`) */
+    planTaxCodes: Record<string, string>;
+    /** Tax behavior per plan code */
+    planTaxBehaviors: Record<string, FFIDTaxBehavior>;
+}
+/**
+ * Human-approved payment configuration snapshot hashed into
+ * `publication.paymentConfigurationHash`.
+ */
+interface FFIDPaymentConfiguration {
+    environment: FFIDCatalogEnvironment;
+    /** Lowercase ISO 4217 currency (e.g. `jpy`) */
+    currency: string;
+    /** Explicit Stripe payment method allow-list (initial sales: `['card']`) */
+    paymentMethodTypes: string[];
+    /** Stripe Dashboard dynamic payment methods must stay disabled for sales */
+    dynamicPaymentMethodsEnabled: boolean;
+    manualInvoiceAllowed: boolean;
+    customerBalanceAllowed: boolean;
+    delayedPaymentMethodsAllowed: boolean;
+    /** Required Stripe Customer invoice credit balance before checkout (spec: 0) */
+    customerInvoiceBalanceRequired: number;
+}
+/** Sales-scope-relevant snapshot of one published plan (subset of the catalog) */
+interface FFIDScopeHashPlan {
+    code: string;
+    priceMonthly: number | null;
+    priceYearly: number | null;
+    currency: string;
+    billingIntervals: FFIDBillingInterval[];
+    taxBehavior: FFIDTaxBehavior;
+    minSeats: number;
+}
+/**
+ * Input of `computeScopeHash` — the published plans' sales conditions plus
+ * the five content/config hashes. Changing any of them changes `scopeHash`,
+ * which invalidates the previous publication approval (fail-closed).
+ */
+interface FFIDScopeHashInput {
+    plans: FFIDScopeHashPlan[];
+    praxisCopyHash: string;
+    ffidCheckoutCopyHash: string;
+    legalDisclosureHash: string;
+    taxConfigurationHash: string;
+    paymentConfigurationHash: string;
+}
+/**
+ * `praxisCopyHash`: hash of the consumer's entire structured sales
+ * presentation (`PRAXIS_SALES_PRESENTATION` — locales, plan display names,
+ * prices, feature matrix, CTAs, eligibility). The consumer re-hashes what it
+ * actually renders and must refuse new sales on mismatch.
+ */
+declare function computePraxisCopyHash(presentation: Record<string, FFIDCanonicalJsonValue>): Promise<string>;
+/** `ffidCheckoutCopyHash`: hash of FFID's structured final-confirmation copy */
+declare function computeFFIDCheckoutCopyHash(checkoutCopy: Record<string, FFIDCanonicalJsonValue>): Promise<string>;
+/**
+ * `legalDisclosureHash`: hash of the canonical body text of the reviewed
+ * legal disclosure document version. Line endings are normalized to LF before
+ * hashing so the digest is independent of platform line-ending conventions;
+ * the text is otherwise hashed byte-exact (no trimming, no Unicode
+ * normalization).
+ */
+declare function computeLegalDisclosureHash(canonicalText: string): Promise<string>;
+/**
+ * `taxConfigurationHash`: hash of the human-approved tax configuration.
+ * Country lists are treated as sets (sorted + deduplicated) so representation
+ * order cannot flip the digest.
+ */
+declare function computeTaxConfigurationHash(config: FFIDTaxConfiguration): Promise<string>;
+/**
+ * `paymentConfigurationHash`: hash of the human-approved payment
+ * configuration. `paymentMethodTypes` is treated as a set.
+ */
+declare function computePaymentConfigurationHash(config: FFIDPaymentConfiguration): Promise<string>;
+/**
+ * `scopeHash`: hash of the published sales scope — plan codes, amounts,
+ * currency, intervals, tax behavior, minimum seats, plus the five embedded
+ * content/config hashes. Plans are sorted by `code`; duplicate codes are
+ * rejected. Embedded hashes are validated for format so a malformed digest
+ * can never be baked into an approval.
+ */
+declare function computeScopeHash(input: FFIDScopeHashInput): Promise<string>;
+
+/** Published catalog methods (#4342 / ASDD-PRICING-002 SP4A) */
+
+/**
+ * Validates the full published-catalog shape the SDK's compile-time types
+ * promise to consumers:
+ * - `service.code` / `service.name` are non-empty strings
+ * - top-level `catalogVersion` equals `publication.catalogVersion`
+ * - `publication.status` is one of the four known literals (unknown statuses
+ *   must fail loud here, NOT be treated as sellable downstream) and
+ *   `publication.environment` is a known environment
+ * - the six approval hashes are lowercase SHA-256 hex; `salesEpoch` is a
+ *   positive integer; timestamps are present (or explicitly null where the
+ *   type allows null)
+ * - every plan carries the full `FFIDPublishedPlan` field set with
+ *   cross-field invariants (an offered interval has its price;
+ *   `minSeats <= maxSeats`), and no plan field NAME mentions Stripe
+ *   (defense-in-depth heuristic — the authoritative no-Stripe-ID guard is
+ *   the FFID server's `.strict()` snapshot schema)
+ *
+ * Throws FFIDSDKError on violation so a server regression surfaces at the
+ * SDK boundary instead of silently reaching a consumer's sales gate.
+ */
+declare function validatePublishedCatalog(catalog: unknown): asserts catalog is FFIDPublishedCatalog;
+
+export { ALL_DENIED_EXCEPT_NECESSARY, type BuildAuthorizeUrlOptions, type BuildAuthorizeUrlResult, CATALOG_HASH_PATTERN, CONSENT_COOKIE_NAME, COOKIE_VERSION, type CookieOptions, FFIDCacheAdapter, type FFIDCanonicalJsonValue, FFIDCatalogEnvironment, FFIDCatalogHashError, type FFIDConsentCategories, type FFIDConsentCategoryCode, type FFIDCookieStoreLike, type FFIDErrorCode, FFIDOAuthUserInfo, type FFIDPaymentConfiguration, FFIDPublishedCatalog, type FFIDScopeHashInput, type FFIDScopeHashPlan, FFIDTaxBehavior, type FFIDTaxConfiguration, FFIDVerifyAccessTokenOptions, FFID_ERROR_CODES, FFID_SESSION_COOKIE_NAME, type HandleCallbackInput, type KVNamespaceLike, type ServerAuthClient, type ServerAuthConfig, type ServerSessionTokens, type ServerTokenResult, canonicalizeCatalogValue, computeFFIDCheckoutCopyHash, computeLegalDisclosureHash, computePaymentConfigurationHash, computePraxisCopyHash, computeScopeHash, computeTaxConfigurationHash, createKVCacheAdapter, createMemoryCacheAdapter, createServerAuthClient, createVerifyAccessToken, decodeConsentCookie, encodeConsentCookie, generateServerState, getFFIDConsentFromCookieHeader, getFFIDConsentFromCookies, hashCanonicalJson, sessionCookies, sha256Hex, validatePublishedCatalog };

package/dist/server/index.js

@@ -850,6 +850,157 @@ var FFID_CATALOG_PUBLICATION_STATUSES = [
 
 // src/shared/catalog-hash.ts
 var CATALOG_HASH_PATTERN = /^[0-9a-f]{64}$/;
+var HEX_RADIX = 16;
+var HEX_DIGITS_PER_BYTE = 2;
+var FFIDCatalogHashError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FFIDCatalogHashError";
+  }
+};
+function isPlainObject(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const proto = Object.getPrototypeOf(value);
+  return proto === Object.prototype || proto === null;
+}
+function canonicalize(value, path) {
+  if (value === null) return "null";
+  switch (typeof value) {
+    case "string":
+      return JSON.stringify(value);
+    case "boolean":
+      return value ? "true" : "false";
+    case "number":
+      if (!Number.isFinite(value)) {
+        throw new FFIDCatalogHashError(
+          `canonicalize: non-finite number at ${path} \u2014 hashes require finite numbers`
+        );
+      }
+      return JSON.stringify(value);
+    case "undefined":
+      throw new FFIDCatalogHashError(
+        `canonicalize: undefined at ${path} \u2014 omit the key entirely or use null`
+      );
+  }
+  if (Array.isArray(value)) {
+    const items = value.map((item, index) => canonicalize(item, `${path}[${index}]`));
+    return `[${items.join(",")}]`;
+  }
+  if (isPlainObject(value)) {
+    const keys = Object.keys(value).sort();
+    const entries = [];
+    for (const key of keys) {
+      const child = value[key];
+      if (child === void 0) {
+        throw new FFIDCatalogHashError(
+          `canonicalize: undefined at ${path}.${key} \u2014 omit the key entirely or use null`
+        );
+      }
+      entries.push(`${JSON.stringify(key)}:${canonicalize(child, `${path}.${key}`)}`);
+    }
+    return `{${entries.join(",")}}`;
+  }
+  throw new FFIDCatalogHashError(
+    `canonicalize: unsupported value type (${typeof value}${typeof value === "object" ? `: ${Object.prototype.toString.call(value)}` : ""}) at ${path} \u2014 only JSON-plain values are hashable`
+  );
+}
+function canonicalizeCatalogValue(value) {
+  return canonicalize(value, "$");
+}
+async function sha256Hex(text) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) {
+    throw new FFIDCatalogHashError(
+      "sha256Hex: Web Crypto (crypto.subtle) is not available in this runtime"
+    );
+  }
+  const digest = await subtle.digest("SHA-256", new TextEncoder().encode(text));
+  return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(HEX_RADIX).padStart(HEX_DIGITS_PER_BYTE, "0")).join("");
+}
+async function hashCanonicalJson(value) {
+  return sha256Hex(canonicalizeCatalogValue(value));
+}
+function assertHashFormat(hash, field) {
+  if (!CATALOG_HASH_PATTERN.test(hash)) {
+    throw new FFIDCatalogHashError(
+      `${field} must be lowercase SHA-256 hex (64 chars), got: ${JSON.stringify(hash)}`
+    );
+  }
+}
+function normalizeStringSet(values) {
+  return [...new Set(values)].sort();
+}
+function compareByCodeUnits(a, b) {
+  if (a.code < b.code) return -1;
+  if (a.code > b.code) return 1;
+  return 0;
+}
+async function computePraxisCopyHash(presentation) {
+  return hashCanonicalJson(presentation);
+}
+async function computeFFIDCheckoutCopyHash(checkoutCopy) {
+  return hashCanonicalJson(checkoutCopy);
+}
+async function computeLegalDisclosureHash(canonicalText) {
+  return sha256Hex(canonicalText.replace(/\r\n?/g, "\n"));
+}
+async function computeTaxConfigurationHash(config) {
+  return hashCanonicalJson({
+    allowedCountries: normalizeStringSet(config.allowedCountries),
+    stripeTaxRegistrations: normalizeStringSet(config.stripeTaxRegistrations),
+    billingAddressRequired: config.billingAddressRequired,
+    planTaxCodes: config.planTaxCodes,
+    planTaxBehaviors: config.planTaxBehaviors
+  });
+}
+async function computePaymentConfigurationHash(config) {
+  return hashCanonicalJson({
+    environment: config.environment,
+    currency: config.currency,
+    paymentMethodTypes: normalizeStringSet(config.paymentMethodTypes),
+    dynamicPaymentMethodsEnabled: config.dynamicPaymentMethodsEnabled,
+    manualInvoiceAllowed: config.manualInvoiceAllowed,
+    customerBalanceAllowed: config.customerBalanceAllowed,
+    delayedPaymentMethodsAllowed: config.delayedPaymentMethodsAllowed,
+    customerInvoiceBalanceRequired: config.customerInvoiceBalanceRequired
+  });
+}
+async function computeScopeHash(input) {
+  assertHashFormat(input.praxisCopyHash, "praxisCopyHash");
+  assertHashFormat(input.ffidCheckoutCopyHash, "ffidCheckoutCopyHash");
+  assertHashFormat(input.legalDisclosureHash, "legalDisclosureHash");
+  assertHashFormat(input.taxConfigurationHash, "taxConfigurationHash");
+  assertHashFormat(input.paymentConfigurationHash, "paymentConfigurationHash");
+  const seenCodes = /* @__PURE__ */ new Set();
+  for (const plan of input.plans) {
+    if (seenCodes.has(plan.code)) {
+      throw new FFIDCatalogHashError(
+        `computeScopeHash: duplicate plan code ${JSON.stringify(plan.code)}`
+      );
+    }
+    seenCodes.add(plan.code);
+  }
+  const plans = [...input.plans].sort(compareByCodeUnits).map((plan) => ({
+    code: plan.code,
+    priceMonthly: plan.priceMonthly,
+    priceYearly: plan.priceYearly,
+    currency: plan.currency,
+    // Set semantics — interval order must not flip the digest.
+    billingIntervals: normalizeStringSet(plan.billingIntervals),
+    taxBehavior: plan.taxBehavior,
+    minSeats: plan.minSeats
+  }));
+  return hashCanonicalJson({
+    plans,
+    praxisCopyHash: input.praxisCopyHash,
+    ffidCheckoutCopyHash: input.ffidCheckoutCopyHash,
+    legalDisclosureHash: input.legalDisclosureHash,
+    taxConfigurationHash: input.taxConfigurationHash,
+    paymentConfigurationHash: input.paymentConfigurationHash
+  });
+}
 
 // src/client/catalog-methods.ts
 var EXT_CATALOG_ENDPOINT = "/api/v1/subscriptions/ext/catalog";
@@ -1132,6 +1283,7 @@ function createMembersMethods(deps) {
 
 // src/client/provisioning-methods.ts
 var USER_PROVISION_ENDPOINT = "/api/v1/ext/users/provision";
+var USER_WELCOME_EMAIL_ENDPOINT = "/api/v1/ext/users/welcome-email";
 var ORGANIZATION_PROVISION_ENDPOINT = "/api/v1/ext/organizations/provision";
 var MAX_PROVISION_MEMBERS = 100;
 var ASSIGNABLE_MEMBER_ROLES = {
@@ -1148,7 +1300,7 @@ function createProvisioningMethods(deps) {
     if (authMode === "service-key") return null;
     return createError(
       "VALIDATION_ERROR",
-      "provisionUser / provisionOrganization \u306F service-key \u8A8D\u8A3C\uFF08X-Service-Api-Key\uFF09\u3067\u306E\u307F\u5229\u7528\u3067\u304D\u307E\u3059\u3002Bearer / cookie \u30E2\u30FC\u30C9\u3067\u306F\u547C\u3073\u51FA\u305B\u307E\u305B\u3093"
+      "provisionUser / sendProvisionWelcomeEmail / provisionOrganization \u306F service-key \u8A8D\u8A3C\uFF08X-Service-Api-Key\uFF09\u3067\u306E\u307F\u5229\u7528\u3067\u304D\u307E\u3059\u3002Bearer / cookie \u30E2\u30FC\u30C9\u3067\u306F\u547C\u3073\u51FA\u305B\u307E\u305B\u3093"
     );
   }
   async function provisionUser(params) {
@@ -1165,6 +1317,17 @@ function createProvisioningMethods(deps) {
       body: JSON.stringify(body)
     });
   }
+  async function sendProvisionWelcomeEmail(params) {
+    const modeError = serviceKeyModeError();
+    if (modeError) return { error: modeError };
+    if (!params.email || !params.email.trim()) {
+      return { error: createError("VALIDATION_ERROR", "email \u306F\u5FC5\u9808\u3067\u3059") };
+    }
+    return fetchWithAuth(USER_WELCOME_EMAIL_ENDPOINT, {
+      method: "POST",
+      body: JSON.stringify({ email: params.email.trim() })
+    });
+  }
   async function provisionOrganization(params) {
     const modeError = serviceKeyModeError();
     if (modeError) return { error: modeError };
@@ -1214,7 +1377,7 @@ function createProvisioningMethods(deps) {
       body: JSON.stringify(body)
     });
   }
-  return { provisionUser, provisionOrganization };
+  return { provisionUser, sendProvisionWelcomeEmail, provisionOrganization };
 }
 
 // src/client/seat-methods.ts
@@ -1488,7 +1651,7 @@ function validateTokenResponse(tokenResponse) {
 }
 
 // src/client/version-check.ts
-var SDK_VERSION = "5.27.0";
+var SDK_VERSION = "5.29.0";
 var SDK_USER_AGENT = `FFID-SDK/${SDK_VERSION} (TypeScript)`;
 var SDK_VERSION_HEADER = "X-FFID-SDK-Version";
 function sdkHeaders() {
@@ -2900,6 +3063,11 @@ function createInquiryMethods(deps) {
         name,
         message,
         category: params.category,
+        // Normalize null ("survey not collected", e.g. forwarded verbatim
+        // from FFIDInquiryFormSubmitData) to undefined so JSON.stringify
+        // drops the key entirely — older FFID deployments never see it and
+        // current ones treat the omission as NULL.
+        acquisitionSource: params.acquisitionSource ?? void 0,
         company: params.company,
         phone: params.phone,
         locale: params.locale,
@@ -3359,7 +3527,7 @@ function createFFIDClient(config) {
     createError,
     serviceCode: config.serviceCode
   });
-  const { provisionUser, provisionOrganization } = createProvisioningMethods({
+  const { provisionUser, sendProvisionWelcomeEmail, provisionOrganization } = createProvisioningMethods({
     fetchWithAuth,
     createError,
     authMode
@@ -3460,6 +3628,7 @@ function createFFIDClient(config) {
     updateMemberRole,
     removeMember,
     provisionUser,
+    sendProvisionWelcomeEmail,
     provisionOrganization,
     getProfile,
     updateProfile,
@@ -3661,11 +3830,11 @@ function getFFIDConsentFromCookieHeader(cookieHeader) {
 
 // src/server/auth/server-state.ts
 var STATE_RANDOM_BYTES2 = 16;
-var HEX_RADIX = 16;
+var HEX_RADIX2 = 16;
 function generateServerState() {
   const bytes = new Uint8Array(STATE_RANDOM_BYTES2);
   globalThis.crypto.getRandomValues(bytes);
-  return Array.from(bytes, (b) => b.toString(HEX_RADIX).padStart(2, "0")).join("");
+  return Array.from(bytes, (b) => b.toString(HEX_RADIX2).padStart(2, "0")).join("");
 }
 
 // src/server/auth/server-oauth-token.ts
@@ -3915,4 +4084,4 @@ function clear(opts = {}) {
 }
 var sessionCookies = { serialize, read, clear };
 
-export { ALL_DENIED_EXCEPT_NECESSARY, CONSENT_COOKIE_NAME, COOKIE_VERSION, FFID_ERROR_CODES, FFID_SESSION_COOKIE_NAME, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createServerAuthClient, createTokenStore, createVerifyAccessToken, decodeConsentCookie, encodeConsentCookie, generateServerState, getFFIDConsentFromCookieHeader, getFFIDConsentFromCookies, sessionCookies };
+export { ALL_DENIED_EXCEPT_NECESSARY, CATALOG_HASH_PATTERN, CONSENT_COOKIE_NAME, COOKIE_VERSION, FFIDCatalogHashError, FFID_CATALOG_ENVIRONMENTS, FFID_CATALOG_PUBLICATION_STATUSES, FFID_ERROR_CODES, FFID_SESSION_COOKIE_NAME, canonicalizeCatalogValue, computeFFIDCheckoutCopyHash, computeLegalDisclosureHash, computePaymentConfigurationHash, computePraxisCopyHash, computeScopeHash, computeTaxConfigurationHash, createFFIDClient, createKVCacheAdapter, createMemoryCacheAdapter, createServerAuthClient, createTokenStore, createVerifyAccessToken, decodeConsentCookie, encodeConsentCookie, generateServerState, getFFIDConsentFromCookieHeader, getFFIDConsentFromCookies, hashCanonicalJson, sessionCookies, sha256Hex, validatePublishedCatalog };

package/dist/server/test/index.d.cts

@@ -1,4 +1,4 @@
-import { k as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-BlVuH6ja.cjs';
+import { q as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-hv2PuUr7.cjs';
 import '../../types-Cjb9J0rL.cjs';
 
 /**

package/dist/server/test/index.d.ts

@@ -1,4 +1,4 @@
-import { k as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-BqnzUmG7.js';
+import { q as FFIDClient, e as FFIDOAuthUserInfo } from '../../ffid-client-DCS-MoxK.js';
 import '../../types-Cjb9J0rL.js';
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feelflow/ffid-sdk",
-  "version": "5.27.0",
+  "version": "5.29.0",
   "description": "FeelFlow ID Platform SDK for React/Next.js applications",
   "keywords": [
     "feelflow",