@feelflow/ffid-sdk 7.2.0 → 8.1.0

package/dist/{ffid-client-QNEFA3mv.d.ts → ffid-client-B0cORHac.d.ts}

@@ -411,6 +411,8 @@ interface FFIDPlanInfo {
     maxSeats: number | null;
     seatSelectionEnabled: boolean;
     trialDays: number;
+    /** flat: period fee; per_seat: multiply by selected quantity. Older servers omit this. */
+    pricingModel?: 'per_seat' | 'flat';
     /**
      * Monthly price in the smallest currency unit.
      *
@@ -450,12 +452,31 @@ interface FFIDSubscriptionDetail {
     trialStart: string | null;
     trialEnd: string | null;
     canceledAt: string | null;
+    /**
+     * `true` while a cancellation is reserved until the period end. `status` stays
+     * `active` until then; the subscription becomes `canceled` at `currentPeriodEnd`.
+     * The reservation can only be withdrawn in the FFID portal (there is no SDK method).
+     */
     cancelAtPeriodEnd: boolean;
-    /** Pending period-end downgrade info (null = no scheduled downgrade) */
+    /**
+     * Change reserved until the period end (null = nothing reserved).
+     *
+     * Every decrease — a lower plan, paid → free, fewer seats, yearly → monthly — is
+     * reserved instead of applied immediately (FFID #6327). The current plan, seats and
+     * interval stay in effect until `scheduledAt`. Withdraw it with `cancelPendingDowngrade()`.
+     */
     pendingDowngrade: {
+        /** Plan in effect after the period end. Equals `planCode` for a seat-only or interval-only reservation. */
         planCode: string;
         planName: string;
+        /** Billing interval in effect after the period end */
         billingInterval: FFIDBillingInterval;
+        /**
+         * Seat count in effect after the period end. `null` = the seat count does not change.
+         * Seat reductions are made in the FFID portal; this lets you show them (8.0.0).
+         * FFID servers released before #6327 omit it, so compare with `== null` at runtime.
+         */
+        quantity: number | null;
         scheduledAt: string;
         requestedAt: string;
     } | null;
@@ -522,7 +543,17 @@ interface FFIDChangePlanParams {
     /** New billing interval (default: keeps current) */
     billingInterval?: FFIDBillingInterval;
 }
-/** Response from change plan endpoint */
+/**
+ * Response from change plan endpoint.
+ *
+ * - An increase (higher plan / monthly → yearly) applies immediately and the difference up to
+ *   the current period end is charged now. `pendingDowngrade` is absent.
+ * - A decrease (lower plan / paid → free / yearly → monthly) is reserved until the period end:
+ *   `pendingDowngrade` is present and `subscription.planCode` is still the current plan.
+ *   Nothing is charged or refunded. A contract that cannot be reserved still changes
+ *   immediately, without a refund: one with no period end, or a paid → paid decrease on a
+ *   contract without a Stripe subscription.
+ */
 interface FFIDChangePlanResponse {
     message: string;
     subscription: {
@@ -535,7 +566,7 @@ interface FFIDChangePlanResponse {
         status: FFIDSubscriptionStatus;
         isUpgrade: boolean;
     };
-    /** Present when downgrade is scheduled for period end instead of immediate */
+    /** Present when the change is a decrease reserved until the period end */
     pendingDowngrade?: {
         planCode: string;
         planName: string;
@@ -551,17 +582,41 @@ interface FFIDCancelSubscriptionParams {
     /** Additional cancellation details */
     reasonDetails?: string;
 }
-/** Response from cancel subscription endpoint */
+/**
+ * Response from cancel subscription endpoint.
+ *
+ * Since 8.0.0 a contract billed through Stripe is **reserved** for cancellation at the period
+ * end (FFID #6327): `status` stays `active`, `cancelAtPeriodEnd` is `true` and `cancelAt` is the
+ * period end. Access continues until then and nothing is refunded. A contract that cannot be
+ * reserved (no Stripe subscription, no period end yet, or Stripe not configured on FFID) is
+ * canceled immediately (`status: 'canceled'`, `cancelAtPeriodEnd: false`, `cancelAt: null`).
+ * Branch on `cancelAtPeriodEnd`, not on whether the contract uses Stripe.
+ *
+ * Do not treat this response as "access revoked". The `subscription.canceled` webhook arrives
+ * at reservation (`source: 'user_initiated'`) and again at the period end
+ * (`source: 'stripe_confirmed'`); see `FFIDSubscriptionCanceledPayload`.
+ */
 interface FFIDCancelSubscriptionResponse {
     message: string;
     subscription: {
         id: string;
         organizationId: string;
+        /** `active` while the cancellation is reserved; `canceled` only for an immediate cancellation */
         status: FFIDSubscriptionStatus;
         canceledAt: string | null;
+        /** `true` when the cancellation is reserved until the period end */
+        cancelAtPeriodEnd: boolean;
+        /** When the reserved cancellation takes effect (the period end). `null` for an immediate cancellation */
+        cancelAt: string | null;
     };
 }
-/** Response from cancel pending downgrade endpoint */
+/**
+ * Response from cancel pending downgrade endpoint.
+ *
+ * Withdraws the reserved change on the Stripe side as well, so the current plan, seats and
+ * interval simply continue after the period end. It does not withdraw a reserved
+ * cancellation — that is done in the FFID portal.
+ */
 interface FFIDCancelPendingDowngradeResponse {
     message: string;
     subscription: {
@@ -593,12 +648,12 @@ interface FFIDPlanChangeLineItem {
 interface FFIDPlanChangePreviewBase {
     /** Discriminant for preview response variants (reserved for future unions with e.g. seat-change previews) */
     type: 'plan-change';
-    /** Current plan display info. `price` is the total for the current quantity (unitPrice × quantity), not per-seat. */
+    /** Current plan display info. `price` is the period total: flat fee, or per-seat price times quantity. */
     currentPlan: {
         name: string;
         price: number;
     };
-    /** New plan display info. `price` is the total for the effective quantity (unitPrice × quantity), not per-seat. */
+    /** New plan display info. `price` is the period total: flat fee, or per-seat price times quantity. */
     newPlan: {
         name: string;
         price: number;
@@ -616,14 +671,18 @@ interface FFIDPlanChangePreviewBase {
     lineItems: FFIDPlanChangeLineItem[];
 }
 /**
- * Plan change proration preview.
+ * Plan change proration preview. It is computed with the same rules as `changePlan()`.
  *
  * `willApplyAtPeriodEnd` is a discriminant that constrains related fields at the type level:
- * - `true`: period-end-deferred downgrade. `proratedAmount` is always 0; `effectiveDate` mirrors
- *   the subscription's `currentPeriodEnd` (may be `null` when the subscription has no active
- *   billing cycle yet — e.g. a pre-Stripe trial or a subscription whose billing cycle is unset).
- * - `false`: immediate change. `effectiveDate` is always `null`; `proratedAmount` is the live
- *   (possibly Stripe-refined) day-basis difference.
+ * - `true`: a decrease reserved until the period end. `proratedAmount` is always 0 (nothing is
+ *   charged or refunded now); `effectiveDate` mirrors the subscription's `currentPeriodEnd`
+ *   (may be `null` when the subscription has no active billing cycle yet).
+ * - `false`: immediate change. `effectiveDate` is always `null`. For an increase,
+ *   `proratedAmount` is the difference up to the current period end that is charged now
+ *   (possibly Stripe-refined). A decrease on a contract that cannot be reserved also lands here:
+ *   `0` for a contract without a Stripe subscription (no refund), but Stripe's prorated amount —
+ *   negative, credited on the next invoice — for a Stripe contract with no period end yet
+ *   (e.g. during a trial).
  */
 type FFIDPlanChangePreview = FFIDPlanChangePreviewBase & ({
     willApplyAtPeriodEnd: true;
@@ -633,7 +692,7 @@ type FFIDPlanChangePreview = FFIDPlanChangePreviewBase & ({
 } | {
     willApplyAtPeriodEnd: false;
     effectiveDate: null;
-    /** Prorated difference charged within the current billing period */
+    /** Difference up to the current period end charged now (see the type doc for the decrease cases) */
     proratedAmount: number;
 });
 /** Response from plan change preview endpoint */
@@ -658,16 +717,32 @@ interface FFIDSeatChangeLineItem {
  * Sister type to `FFIDPlanChangePreview`. The shared `type` discriminant lets
  * consumers narrow a preview payload without inspecting unrelated fields.
  *
+ * - `willApplyAtPeriodEnd=true`: a seat reduction reserved until the period end.
+ *   `proratedAmount` is 0 and `effectiveDate` is when the new seat count applies.
+ * - Otherwise the change applies immediately. For an increase, `proratedAmount` is the amount
+ *   charged now up to the current period end. A reduction that cannot be reserved is normally
+ *   `0`, but can be negative (a credit on the next invoice) for a Stripe contract with no period
+ *   end yet or when only the contract unit price is known.
  * - `isEstimate=true` (default when Stripe is not configured or data is unavailable):
- *   `proratedAmount` is computed locally as `(newQuantity - currentQuantity) * unitPrice`.
- * - `isEstimate=false`: `proratedAmount` reflects Stripe's live proration calculation.
- *
- * `nextInvoiceAmount` is always a local estimate (`unitPrice * newQuantity`).
- *
- * `pricingUnavailable=true` indicates the plan uses custom pricing with a zero unit
- * price (Enterprise). Consumers should hide monetary amounts in this case.
+ *   `proratedAmount` is computed locally. `isEstimate=false`: it reflects Stripe's live
+ *   proration calculation.
+ *
+ * `nextInvoiceAmount` is a local estimate: flat period fee, or `unitPrice * newQuantity`.
+ * Flat capacity changes have zero prorated cost.
+ *
+ * `pricingUnavailable=true` means custom pricing or an unverified contracted Stripe
+ * Price. Hide amounts; zero is not a quote. `custom_pricing` permits the existing
+ * unbilled seat-change flow. Require another preview before confirmation only when
+ * pricing is unavailable and the reason is not `custom_pricing`. `stripe_error` also
+ * covers invoice/address failures after the contract price is known; use
+ * `pricingUnavailable`, not the reason alone, to decide whether to hide amounts.
+ * `no_stripe_data` means invoice proration is unavailable even if the contract unit
+ * price is known. Portal seat PUT independently enforces subscription limits;
+ * external consumers should guide users to the FFID portal for seat changes.
  */
 interface FFIDSeatChangePreview {
+    /** flat: unitPrice is the whole period fee; per_seat: multiply by capacity. */
+    pricingModel?: 'per_seat' | 'flat';
     /** Discriminant for preview response variants (pairs with `FFIDPlanChangePreview.type`) */
     type: 'seat-change';
     currentQuantity: number;
@@ -676,20 +751,28 @@ interface FFIDSeatChangePreview {
     unitPrice: number;
     billingInterval: FFIDBillingInterval;
     /**
-     * Prorated cost for the current billing period. Negative when seats are decreased
-     * (credit). `0` when `pricingUnavailable === true` (Enterprise custom pricing).
+     * Amount charged now for the rest of the current billing period. A reserved seat reduction
+     * (`willApplyAtPeriodEnd: true`) is always `0`; see the type doc for reductions that cannot
+     * be reserved. Also `0` when `pricingUnavailable === true`; hide it instead of quoting zero.
      */
     proratedAmount: number;
-    /** Next invoice full amount — always a local estimate (`unitPrice * newQuantity`) */
+    /** Next invoice full amount — flat period fee or per-seat price times newQuantity */
     nextInvoiceAmount: number;
     nextInvoiceDate: string | null;
     currency: FFIDSupportedCurrency;
-    /** true when proratedAmount is estimated from local prices rather than Stripe proration data */
+    /** true when proratedAmount is a local estimate rather than Stripe invoice/proration data */
     isEstimate: boolean;
-    /** true when unit price is 0 due to custom pricing (Enterprise) — hide monetary amounts */
+    /** Hide amounts: custom pricing or contracted Stripe Price could not be verified. */
     pricingUnavailable?: boolean;
     /** Reason why `isEstimate` is true. Only meaningful when `isEstimate === true`. */
     estimateReason?: 'no_stripe_data' | 'custom_pricing' | 'stripe_error';
+    /**
+     * `true` when the seat reduction would be reserved until the period end (8.0.0).
+     * Absent or `false` = the change applies immediately.
+     */
+    willApplyAtPeriodEnd?: boolean;
+    /** When the reserved seat count applies (present when `willApplyAtPeriodEnd` is `true`) */
+    effectiveDate?: string | null;
     lineItems: FFIDSeatChangeLineItem[];
 }
 /** Response from seat change preview endpoint */
@@ -774,6 +857,7 @@ interface FFIDProvisionUserProfileInput {
     /** Display name (1–255 chars). */
     displayName?: string;
     /** Company name (≤255 chars). */
+    /** @deprecated Accepted for compatibility but ignored by FFID. */
     companyName?: string;
     /** Department (≤255 chars). */
     department?: string;
@@ -1475,7 +1559,7 @@ interface FFIDUserProfile {
     avatarUrl: string | null;
     /** Phone number (nullable when not set) */
     phone: string | null;
-    /** Company name (nullable when not set) */
+    /** @deprecated Individual employer name is retired; this field is always null. Use the organization entity's name. */
     companyName: string | null;
     /** Department (nullable when not set) */
     department: string | null;
@@ -1556,7 +1640,7 @@ interface FFIDUpdateUserProfileRequest {
     displayName?: string | null;
     /** Phone number (null clears the field) */
     phone?: string | null;
-    /** Company name (null clears the field) */
+    /** @deprecated Accepted for compatibility but ignored. Use the organization entity's name. */
     companyName?: string | null;
     /** Department (null clears the field) */
     department?: string | null;
@@ -1922,6 +2006,7 @@ interface FFIDOAuthUserInfo {
     emailVerified?: boolean | undefined;
     name: string | null;
     picture: string | null;
+    /** @deprecated Individual employer name is retired; always null. Use organizationName. */
     companyName?: string | null | undefined;
     department?: string | null | undefined;
     position?: string | null | undefined;
@@ -2356,7 +2441,9 @@ declare function createFFIDClient(config: FFIDConfig): {
         prompt?: FFIDPrompt;
     }) => string;
     getLogoutUrl: (postLogoutRedirectUri?: string) => string;
-    getSignupUrl: (redirectUrl?: string) => string;
+    getSignupUrl: (redirectUrl?: string, options?: {
+        inviteToken?: string;
+    }) => string;
     createError: (code: string, message: string) => FFIDError;
     exchangeCodeForTokens: (code: string, codeVerifier?: string, opts?: ExchangeCodeForTokensOptions) => Promise<FFIDApiResponse<void>>;
     refreshAccessToken: () => Promise<FFIDApiResponse<void>>;

package/dist/{index-BMKhKhzF.d.cts → index-BG7g99pK.d.cts}

@@ -411,6 +411,7 @@ interface FFIDOAuthUserInfo {
     emailVerified?: boolean | undefined;
     name: string | null;
     picture: string | null;
+    /** @deprecated Individual employer name is retired; always null. Use organizationName. */
     companyName?: string | null | undefined;
     department?: string | null | undefined;
     position?: string | null | undefined;

package/dist/{index-BMKhKhzF.d.ts → index-BG7g99pK.d.ts}

@@ -411,6 +411,7 @@ interface FFIDOAuthUserInfo {
     emailVerified?: boolean | undefined;
     name: string | null;
     picture: string | null;
+    /** @deprecated Individual employer name is retired; always null. Use organizationName. */
     companyName?: string | null | undefined;
     department?: string | null | undefined;
     position?: string | null | undefined;