@streamoid/settings 0.12.4 → 0.14.0

package/dist/index.d.mts

@@ -673,7 +673,9 @@ interface SharedPoolBalance {
     remaining: number;
     /** When the sponsor's billing cycle ends and the allowance starts again. */
     cycleEnd: string;
-    /** The member's own credits: still its own, but paused while it is a member. */
+    /** When the share stops on its own (ISO); null or absent when it runs until removed. */
+    endsAt?: string | null;
+    /** The member's own credits, spent before the pool's. */
     ownCredits?: number;
 }
 interface AvailableCreditsResponse {
@@ -703,8 +705,28 @@ interface BillingSubscription {
     /** Stripe product id; used to look up the matching product in fetched plans. */
     stripeProductId?: string;
 }
+/**
+ * Whether the workspace gets paid features, and why: `plan` (its own paid
+ * plan) or `pool` (it spends a sponsor's shared credits, on its free plan).
+ * The plan and billing actions are unchanged by it; see `./entitlement`.
+ */
+interface BillingEntitlement {
+    paid: boolean;
+    source: "plan" | "pool" | null;
+    /** The sponsor's workspace id, for `pool`. */
+    sponsorWorkspaceId?: string;
+    sponsorName?: string;
+    /** When the sharing ends (ISO); null or absent when it runs until removed. */
+    endsAt?: string | null;
+}
 interface SubscriptionResponse {
     data: BillingSubscription | null;
+    /**
+     * Billing's top-level `entitlement` (beside `data`), passed through.
+     * Absent on servers from before it, and from hosts that drop it: then the
+     * plan alone decides, as before.
+     */
+    entitlement?: BillingEntitlement | null;
 }
 interface PriceMetadata {
     name: string;
@@ -894,6 +916,8 @@ interface CreditPoolMember {
         end: string;
         base: number;
     };
+    /** When the share stops on its own (ISO); null or absent when it runs until removed. */
+    endsAt?: string | null;
     note?: string;
     requestedBy?: string;
     createdBy?: string;
@@ -926,10 +950,14 @@ interface AddCreditPoolMemberInput {
     value: number;
     /** Why — required, at most 500 characters. */
     note: string;
+    /** When the share stops on its own (an ISO date in the future); null or absent for never. */
+    endsAt?: string | null;
 }
 interface UpdateCreditPoolMemberInput {
     mode: CreditPoolMode;
     value: number;
+    /** A new end date (ISO, in the future), or null to clear it; absent leaves it as it is. */
+    endsAt?: string | null;
 }
 /** A workspace credits can be shared with (another workspace of the organization). */
 interface CreditPoolCandidate {
@@ -957,7 +985,10 @@ interface SettingsApiAdapter {
     fetchPlans: () => Promise<ProductsResponse>;
     /**
      * Current active subscription. Returns `{ data: null }` when the workspace
-     * has no plan yet (free tier).
+     * has no plan yet (free tier). Pass billing's top-level `entitlement`
+     * through as `entitlement`. For billing's 404 (no subscription) that carries
+     * one, resolve `{ data: null, entitlement }`, or throw an error that keeps
+     * the response body (`body`, `data` or `response.data`).
      */
     fetchCurrentPlan: () => Promise<SubscriptionResponse>;
     /** Available credit balance for the active workspace. */
@@ -1416,7 +1447,7 @@ type IconProps = Omit<SVGProps<SVGSVGElement>, 'color' | 'strokeWidth' | 'width'
 };
 declare const SiconKey: ({ color, strokeWidth, size, ...props }: IconProps) => react.JSX.Element;
 
-declare function BillingContent({ embedded, showPlans: showPlansProp, onShowPlansChange, showPerUserLimits: showPerUserLimitsProp, onShowPerUserLimitsChange, showSharedCredits: showSharedCreditsProp, onShowSharedCreditsChange, }?: {
+declare function BillingContent({ embedded, showPlans: showPlansProp, onShowPlansChange, showPerUserLimits: showPerUserLimitsProp, onShowPerUserLimitsChange, showSharedCredits: showSharedCreditsProp, onShowSharedCreditsChange, onEntitlementChange, }?: {
     embedded?: boolean;
     /** Controlled "plans" sub-view flag. When provided, the host (settings
      *  wrapper) owns it so it can hide the sub-nav + show the Plans breadcrumb. */
@@ -1431,6 +1462,14 @@ declare function BillingContent({ embedded, showPlans: showPlansProp, onShowPlan
      *  workspace is in an organization. */
     showSharedCredits?: boolean;
     onShowSharedCreditsChange?: (open: boolean) => void;
+    /** Called once the current plan has loaded, and again when it changes:
+     *  billing's `entitlement` (null from servers without it) and whether the
+     *  workspace gets paid features. A workspace spending a sponsor's shared
+     *  credits is `paid` on its free plan; gate features on this, not the plan. */
+    onEntitlementChange?: (state: {
+        entitlement: BillingEntitlement | null;
+        paid: boolean;
+    }) => void;
 }): react__default.JSX.Element;
 
 /**
@@ -2082,18 +2121,63 @@ declare function formatPoolSplit(split: {
 }): string;
 /** "20% · 200 credits this cycle", or "200 credits this cycle" for a fixed share. */
 declare function describeAllowance(member: Pick<CreditPoolMember, "mode" | "value" | "allowance">): string;
+/**
+ * When a share stops on its own, as the Ends field picks it. `never` is
+ * today's behaviour: the share renews every cycle until it is removed.
+ */
+type PoolExpiryChoice = {
+    kind: "never";
+} | {
+    kind: "month";
+} | {
+    kind: "months";
+    months: number;
+} | {
+    kind: "year";
+}
+/** A local calendar day, `YYYY-MM-DD` (what `<input type="date">` gives). */
+ | {
+    kind: "date";
+    date: string;
+};
+declare const POOL_EXPIRY_MAX_MONTHS = 120;
+/** A local calendar day as `YYYY-MM-DD`. */
+declare function toLocalDateInput(date: Date): string;
+/** The earliest day the date picker allows: tomorrow, in local time. */
+declare function minPoolEndDate(now?: Date): string;
+type PoolEndsAtResult = {
+    ok: true;
+    value: string | null;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * The `endsAt` to send for a choice, as an ISO string, or `null` for Never.
+ * Months and a year count from `now`; a date is the start of that day in the
+ * admin's local time and must be after today.
+ */
+declare function poolEndsAtFrom(choice: PoolExpiryChoice, now?: Date): PoolEndsAtResult;
+/** The Ends field's starting choice for a share: Never, or its end date's day. */
+declare function expiryChoiceFor(member: Pick<CreditPoolMember, "endsAt"> | null | undefined): PoolExpiryChoice;
+/** When a share ends: "Mar 1, 2027", or "Never" when it runs until removed. */
+declare function formatPoolEndsAt(endsAt: string | null | undefined): string;
+/** The member banner's line on when sharing stops: "Sharing ends on Mar 1, 2027." or "Sharing ends: Never." */
+declare function sharedPoolEndsText(pool: Pick<SharedPoolBalance, "endsAt">): string;
+/** Whether the allowance starts again at `cycleEnd`: not when the share has ended by then. */
+declare function poolRenewsAtCycleEnd(pool: Pick<SharedPoolBalance, "endsAt" | "cycleEnd">): boolean;
 /** The other workspace's name, or a stand-in when it could not be resolved. */
 declare function poolWorkspaceName(name: string | null | undefined): string;
 /** The member's Billing banner: "Credits shared by Agency: 80 of 200 left this cycle". */
 declare function sharedPoolBannerText(pool: Pick<SharedPoolBalance, "sponsorName" | "allowance" | "remaining">): string;
 /**
- * The line under the member's banner when its own credits could not be spent
- * with the pool's. Billing now spends them first (see `ownCreditsFirstText`);
- * kept for hosts that still show it.
+ * Was the line saying a member's own credits were paused while it used the
+ * pool's. Billing spends them first, so it now answers `ownCreditsFirstText`
+ * for hosts that still call it.
  *
  * @deprecated Use `ownCreditsFirstText`.
  */
-declare function pausedOwnCreditsText(pool: Pick<SharedPoolBalance, "ownCredits">): string;
+declare function pausedOwnCreditsText(_pool?: Pick<SharedPoolBalance, "ownCredits">): string;
 /** The line under the member's banner: whose credits a job spends, in order. */
 declare function ownCreditsFirstText(): string;
 interface CreditsMeter {
@@ -2151,6 +2235,78 @@ declare function poolErrorMessage(failure: unknown): string | null;
  */
 declare function SharedCreditsView(): react.JSX.Element;
 
+/**
+ * Whether a workspace gets paid features, and why. Billing reports it at the
+ * top level of the current-subscription answer, beside `data` (200:
+ * `{ success, data, entitlement }`; 404: `{ error, entitlement }`), and
+ * leaves the plan as it is: a workspace spending another's shared credits (a
+ * "sponsored" workspace) still shows the free plan, with
+ * `entitlement.source: 'pool'`.
+ *
+ * So the plan — and every billing action: Upgrade, Cancel downgrade, Buy
+ * credits — stays decided by the plan's amount, and only features are gated
+ * on `entitlement.paid`. Billing servers from before entitlement send none;
+ * then a workspace is paid exactly when its plan is, as before.
+ */
+/** `entitlement` as billing sends it, or null when it is absent or malformed. */
+declare function parseBillingEntitlement(value: unknown): BillingEntitlement | null;
+/**
+ * The `entitlement` of a current-subscription answer: `body.entitlement`,
+ * never `body.data.entitlement` (`data` is the subscription).
+ */
+declare function entitlementFromBody(body: unknown): BillingEntitlement | null;
+/**
+ * The entitlement a failed read carries: billing's 404 for a workspace with
+ * no subscription of its own still says whether a pool entitles it. The body
+ * is looked for where hosts keep it — the failure itself, `body`, `data`
+ * (`UserFacingError`), `response.data` (axios) and `cause` — to a shallow
+ * depth. Null when there is none.
+ */
+declare function entitlementFromFailure(failure: unknown): BillingEntitlement | null;
+/** Paid by the workspace's own plan: what Buy credits and the plan actions go by. */
+declare function isPaidPlan(subscription: Pick<BillingSubscription, "plan"> | null | undefined): boolean;
+/**
+ * Whether the workspace gets paid features: `entitlement.paid` when billing
+ * sent one, else its own plan being paid (servers from before entitlement).
+ */
+declare function hasPaidFeatures({ entitlement, subscription, }: {
+    entitlement: BillingEntitlement | null | undefined;
+    subscription: Pick<BillingSubscription, "plan"> | null | undefined;
+}): boolean;
+/** A workspace spending another's shared credits, by its entitlement. */
+declare function isSponsoredEntitlement(entitlement: BillingEntitlement | null | undefined): entitlement is BillingEntitlement & {
+    source: "pool";
+};
+/** "Credits shared by Agency." plus " Sharing ends on Mar 1, 2027." when it ends on its own. */
+declare function sponsoredCreditsText(entitlement: Pick<BillingEntitlement, "sponsorName" | "endsAt">): string;
+interface CurrentPlanState {
+    /** The workspace's own subscription; null without one. */
+    subscription: BillingSubscription | null;
+    /** Null when billing sent none (servers from before entitlement). */
+    entitlement: BillingEntitlement | null;
+    /** Gate features on this; see `hasPaidFeatures`. */
+    paid: boolean;
+}
+/**
+ * Read the current plan and its entitlement through the host's
+ * `fetchCurrentPlan`. A failure that carries an entitlement — billing's 404
+ * for a sponsored workspace with no subscription of its own — is not an
+ * error: it answers no subscription with that entitlement. Any other failure
+ * is thrown, as before.
+ */
+declare function loadCurrentPlan(fetchCurrentPlan: () => Promise<SubscriptionResponse>): Promise<CurrentPlanState>;
+
+/**
+ * `loadCurrentPlan` as a hook, for a host gating features on `paid`. Reloads
+ * when `key` (e.g. the workspace id) changes; `fetchCurrentPlan` may be a new
+ * function every render. `state` is null while loading, after a failure, and
+ * while `key` is null.
+ */
+declare function useBillingEntitlement(fetchCurrentPlan: (() => Promise<SubscriptionResponse>) | null | undefined, key: string | null | undefined): {
+    state: CurrentPlanState | null;
+    loading: boolean;
+};
+
 type CreditPoolMemberModalProps = {
     kind: "add";
     /** Workspaces credits can be shared with. */
@@ -2278,4 +2434,4 @@ interface AppSettingsRowProps {
 }
 declare function AppSettingsRow({ title, description, summary, href, onClick, disabled, disabledReason, ariaLabel, trailing }: AppSettingsRowProps): react.JSX.Element;
 
-export { APP_KEYS, type AddCreditPoolMemberInput, AdministrationOverview, type AdministrationOverviewProps, type AdministrativeNavigationOptions, type ApiToken, type AppKey, AppSettingsHeader, type AppSettingsHeaderProps, AppSettingsPage, type AppSettingsPageProps, AppSettingsRow, type AppSettingsRowProps, AppSettingsSection, type AppSettingsSectionProps, type AvailableCreditsResponse, BillingContent, type BillingEventPayload, type BillingProduct, type BillingSubscription, BuyCreditsModal, type BuyCreditsPayload, type BuyCreditsResponse, ConfirmDeleteModal, ConfirmLeaveModal, type ConnectedApp, ConnectedAppsContent, type CreatedToken, type CreditCycleUnit, type CreditLimitValidation, type CreditPoolCandidate, type CreditPoolFormerMember, type CreditPoolMember, CreditPoolMemberModal, type CreditPoolMemberModalProps, type CreditPoolMemberStatus, type CreditPoolMode, type CreditPoolResponse, type CreditsMeter, type CustomCreditInfo, type CustomCreditResponse, DEFAULT_PERMISSIONS, DEFAULT_USER_LANGUAGE, ExportDateModal, InviteUpdateModal, type InvoicePdfResponse, type MemberCreditLimit, MemberCreditLimitModal, type MemberCreditLimitRow, type MemberCreditLimitSource, type MemberCreditLimitsResponse, MemberListFrame, type MemberListFrameProps, type MemberListTab, MemberListToolbar, type MemberListToolbarProps, type MemberPermissionsPayload, OrganizationContent, type OrganizationData, type OrganizationDetails, OrganizationIntegrationsContent, type OrganizationInvite, type OrganizationJoinRequest, type OrganizationJoinableWorkspace, type OrganizationMember, OrganizationMemberModal, type OrganizationMemberModalProps, type OrganizationMemberRole, OrganizationModal, OrganizationPicker, type OrganizationPickerItem, type OrganizationPickerProps, type OrganizationPickerType, type OrganizationView, type OrganizationWorkspaceItem, POOL_ERROR_CODES, POOL_NOTE_MAX_LENGTH, PerUserLimitsView, type PoolErrorCode, type PoolValueValidation, type Price, type PriceMetadata, type ProductsResponse, ProfileAvatar, ProfileTab, REMOVE_REASON_MAX_LENGTH, ReferralTab, RemovePoolMemberModal, type RemovePoolMemberModalProps, SCOPE_LABELS, ScopeHeader, type ScopeHeaderProps, type ServiceItem, type SettingsAdapters, SettingsAdaptersProvider, type SettingsApiAdapter, type SettingsAuthAdapter, type SettingsAuthUser, SettingsContent, type SettingsContentProps, type SettingsImageUploadAdapter, type SettingsIntegrationsAdapter, type SettingsNavigationAdapter, type SettingsOrganizationAdapter, type SettingsOrganizationCreateOptions, type SettingsOrganizationCurrent, type SettingsOrganizationJoinableItem, type SettingsOrganizationListItem, type SettingsOrganizationType, type SettingsScope, type SettingsTab, type SettingsToastAdapter, SettingsTooltip, type SettingsTooltipPlacement, type SettingsTooltipProps, type SettingsWorkspaceAdapter, type SettingsWorkspaceCurrent, type SettingsWorkspaceListItem, SharedCreditsView, type SharedPoolBalance, SiconKey, type StoreItem, type SubscriptionPlan, type SubscriptionResponse, TAB_DESCRIPTIONS, TAB_LABELS, TAB_SCOPE, TAB_TO_URL, type TeamMember, TeamsContent, type TokenExpiry, TokensContent, URL_TO_TAB, USER_LANGUAGES, type UpdateCreditPoolMemberInput, type UpdateSubscriptionPayload, type UpdateSubscriptionResponse, type UsageHistoryItem, type UsageHistoryResponse, type UserLanguage, type UserPermissions, WORKSPACE_LIST_PAGE_SIZE, type WorkspaceData, WorkspaceGeneralTab, type WorkspaceGeneralTabProps, type WorkspaceInvite, type WorkspaceListOrganization, WorkspaceListTab, type WorkspaceMember, WorkspaceModal, type WorkspaceOrganization, type WorkspaceOrganizationRequest, WorkspacePicker, type WorkspacePickerGroup, type WorkspacePickerItem, type WorkspacePickerProps, WorkspaceTab, type WorkspaceUsageResponse, belowUsageReason, canShowSharedCredits, cleanCreditLimitInput, cleanPoolValueInput, countLabel, creditCycleUnit, creditsMeter, deriveWorkspaceInvitePermission, describeAllowance, describeDefaultLimit, describeMemberLimit, findBillingError, findPoolError, formatCreditLimit, formatCredits, formatPoolSplit, groupWorkspaceList, isLimitBelowUsage, joinMembersWithLimits, lastUsedLabel, limitBelowUsageUsed, limitSourceLabel, loadWorkspaceOrganization, memberRoleUpdate, minimumCreditLimit, ownCreditsFirstText, pausedOwnCreditsText, poolErrorMessage, poolWorkspaceName, readSettingsCaller, rememberSettingsCaller, resolveSettingsTabFromPath, roundCredits, settingsReturnTarget, sharedPoolBannerText, useSettingsAdapters, useWorkspaceInvitePermission, useWorkspaceOrganization, usedByNamesFrom, usedByWorkspaceKey, userLanguageLabel, validateCreditLimitInput, validateDefaultCreditLimitInput, validatePoolText, validatePoolValue };
+export { APP_KEYS, type AddCreditPoolMemberInput, AdministrationOverview, type AdministrationOverviewProps, type AdministrativeNavigationOptions, type ApiToken, type AppKey, AppSettingsHeader, type AppSettingsHeaderProps, AppSettingsPage, type AppSettingsPageProps, AppSettingsRow, type AppSettingsRowProps, AppSettingsSection, type AppSettingsSectionProps, type AvailableCreditsResponse, BillingContent, type BillingEntitlement, type BillingEventPayload, type BillingProduct, type BillingSubscription, BuyCreditsModal, type BuyCreditsPayload, type BuyCreditsResponse, ConfirmDeleteModal, ConfirmLeaveModal, type ConnectedApp, ConnectedAppsContent, type CreatedToken, type CreditCycleUnit, type CreditLimitValidation, type CreditPoolCandidate, type CreditPoolFormerMember, type CreditPoolMember, CreditPoolMemberModal, type CreditPoolMemberModalProps, type CreditPoolMemberStatus, type CreditPoolMode, type CreditPoolResponse, type CreditsMeter, type CurrentPlanState, type CustomCreditInfo, type CustomCreditResponse, DEFAULT_PERMISSIONS, DEFAULT_USER_LANGUAGE, ExportDateModal, InviteUpdateModal, type InvoicePdfResponse, type MemberCreditLimit, MemberCreditLimitModal, type MemberCreditLimitRow, type MemberCreditLimitSource, type MemberCreditLimitsResponse, MemberListFrame, type MemberListFrameProps, type MemberListTab, MemberListToolbar, type MemberListToolbarProps, type MemberPermissionsPayload, OrganizationContent, type OrganizationData, type OrganizationDetails, OrganizationIntegrationsContent, type OrganizationInvite, type OrganizationJoinRequest, type OrganizationJoinableWorkspace, type OrganizationMember, OrganizationMemberModal, type OrganizationMemberModalProps, type OrganizationMemberRole, OrganizationModal, OrganizationPicker, type OrganizationPickerItem, type OrganizationPickerProps, type OrganizationPickerType, type OrganizationView, type OrganizationWorkspaceItem, POOL_ERROR_CODES, POOL_EXPIRY_MAX_MONTHS, POOL_NOTE_MAX_LENGTH, PerUserLimitsView, type PoolEndsAtResult, type PoolErrorCode, type PoolExpiryChoice, type PoolValueValidation, type Price, type PriceMetadata, type ProductsResponse, ProfileAvatar, ProfileTab, REMOVE_REASON_MAX_LENGTH, ReferralTab, RemovePoolMemberModal, type RemovePoolMemberModalProps, SCOPE_LABELS, ScopeHeader, type ScopeHeaderProps, type ServiceItem, type SettingsAdapters, SettingsAdaptersProvider, type SettingsApiAdapter, type SettingsAuthAdapter, type SettingsAuthUser, SettingsContent, type SettingsContentProps, type SettingsImageUploadAdapter, type SettingsIntegrationsAdapter, type SettingsNavigationAdapter, type SettingsOrganizationAdapter, type SettingsOrganizationCreateOptions, type SettingsOrganizationCurrent, type SettingsOrganizationJoinableItem, type SettingsOrganizationListItem, type SettingsOrganizationType, type SettingsScope, type SettingsTab, type SettingsToastAdapter, SettingsTooltip, type SettingsTooltipPlacement, type SettingsTooltipProps, type SettingsWorkspaceAdapter, type SettingsWorkspaceCurrent, type SettingsWorkspaceListItem, SharedCreditsView, type SharedPoolBalance, SiconKey, type StoreItem, type SubscriptionPlan, type SubscriptionResponse, TAB_DESCRIPTIONS, TAB_LABELS, TAB_SCOPE, TAB_TO_URL, type TeamMember, TeamsContent, type TokenExpiry, TokensContent, URL_TO_TAB, USER_LANGUAGES, type UpdateCreditPoolMemberInput, type UpdateSubscriptionPayload, type UpdateSubscriptionResponse, type UsageHistoryItem, type UsageHistoryResponse, type UserLanguage, type UserPermissions, WORKSPACE_LIST_PAGE_SIZE, type WorkspaceData, WorkspaceGeneralTab, type WorkspaceGeneralTabProps, type WorkspaceInvite, type WorkspaceListOrganization, WorkspaceListTab, type WorkspaceMember, WorkspaceModal, type WorkspaceOrganization, type WorkspaceOrganizationRequest, WorkspacePicker, type WorkspacePickerGroup, type WorkspacePickerItem, type WorkspacePickerProps, WorkspaceTab, type WorkspaceUsageResponse, belowUsageReason, canShowSharedCredits, cleanCreditLimitInput, cleanPoolValueInput, countLabel, creditCycleUnit, creditsMeter, deriveWorkspaceInvitePermission, describeAllowance, describeDefaultLimit, describeMemberLimit, entitlementFromBody, entitlementFromFailure, expiryChoiceFor, findBillingError, findPoolError, formatCreditLimit, formatCredits, formatPoolEndsAt, formatPoolSplit, groupWorkspaceList, hasPaidFeatures, isLimitBelowUsage, isPaidPlan, isSponsoredEntitlement, joinMembersWithLimits, lastUsedLabel, limitBelowUsageUsed, limitSourceLabel, loadCurrentPlan, loadWorkspaceOrganization, memberRoleUpdate, minPoolEndDate, minimumCreditLimit, ownCreditsFirstText, parseBillingEntitlement, pausedOwnCreditsText, poolEndsAtFrom, poolErrorMessage, poolRenewsAtCycleEnd, poolWorkspaceName, readSettingsCaller, rememberSettingsCaller, resolveSettingsTabFromPath, roundCredits, settingsReturnTarget, sharedPoolBannerText, sharedPoolEndsText, sponsoredCreditsText, toLocalDateInput, useBillingEntitlement, useSettingsAdapters, useWorkspaceInvitePermission, useWorkspaceOrganization, usedByNamesFrom, usedByWorkspaceKey, userLanguageLabel, validateCreditLimitInput, validateDefaultCreditLimitInput, validatePoolText, validatePoolValue };

package/dist/index.d.ts

@@ -673,7 +673,9 @@ interface SharedPoolBalance {
     remaining: number;
     /** When the sponsor's billing cycle ends and the allowance starts again. */
     cycleEnd: string;
-    /** The member's own credits: still its own, but paused while it is a member. */
+    /** When the share stops on its own (ISO); null or absent when it runs until removed. */
+    endsAt?: string | null;
+    /** The member's own credits, spent before the pool's. */
     ownCredits?: number;
 }
 interface AvailableCreditsResponse {
@@ -703,8 +705,28 @@ interface BillingSubscription {
     /** Stripe product id; used to look up the matching product in fetched plans. */
     stripeProductId?: string;
 }
+/**
+ * Whether the workspace gets paid features, and why: `plan` (its own paid
+ * plan) or `pool` (it spends a sponsor's shared credits, on its free plan).
+ * The plan and billing actions are unchanged by it; see `./entitlement`.
+ */
+interface BillingEntitlement {
+    paid: boolean;
+    source: "plan" | "pool" | null;
+    /** The sponsor's workspace id, for `pool`. */
+    sponsorWorkspaceId?: string;
+    sponsorName?: string;
+    /** When the sharing ends (ISO); null or absent when it runs until removed. */
+    endsAt?: string | null;
+}
 interface SubscriptionResponse {
     data: BillingSubscription | null;
+    /**
+     * Billing's top-level `entitlement` (beside `data`), passed through.
+     * Absent on servers from before it, and from hosts that drop it: then the
+     * plan alone decides, as before.
+     */
+    entitlement?: BillingEntitlement | null;
 }
 interface PriceMetadata {
     name: string;
@@ -894,6 +916,8 @@ interface CreditPoolMember {
         end: string;
         base: number;
     };
+    /** When the share stops on its own (ISO); null or absent when it runs until removed. */
+    endsAt?: string | null;
     note?: string;
     requestedBy?: string;
     createdBy?: string;
@@ -926,10 +950,14 @@ interface AddCreditPoolMemberInput {
     value: number;
     /** Why — required, at most 500 characters. */
     note: string;
+    /** When the share stops on its own (an ISO date in the future); null or absent for never. */
+    endsAt?: string | null;
 }
 interface UpdateCreditPoolMemberInput {
     mode: CreditPoolMode;
     value: number;
+    /** A new end date (ISO, in the future), or null to clear it; absent leaves it as it is. */
+    endsAt?: string | null;
 }
 /** A workspace credits can be shared with (another workspace of the organization). */
 interface CreditPoolCandidate {
@@ -957,7 +985,10 @@ interface SettingsApiAdapter {
     fetchPlans: () => Promise<ProductsResponse>;
     /**
      * Current active subscription. Returns `{ data: null }` when the workspace
-     * has no plan yet (free tier).
+     * has no plan yet (free tier). Pass billing's top-level `entitlement`
+     * through as `entitlement`. For billing's 404 (no subscription) that carries
+     * one, resolve `{ data: null, entitlement }`, or throw an error that keeps
+     * the response body (`body`, `data` or `response.data`).
      */
     fetchCurrentPlan: () => Promise<SubscriptionResponse>;
     /** Available credit balance for the active workspace. */
@@ -1416,7 +1447,7 @@ type IconProps = Omit<SVGProps<SVGSVGElement>, 'color' | 'strokeWidth' | 'width'
 };
 declare const SiconKey: ({ color, strokeWidth, size, ...props }: IconProps) => react.JSX.Element;
 
-declare function BillingContent({ embedded, showPlans: showPlansProp, onShowPlansChange, showPerUserLimits: showPerUserLimitsProp, onShowPerUserLimitsChange, showSharedCredits: showSharedCreditsProp, onShowSharedCreditsChange, }?: {
+declare function BillingContent({ embedded, showPlans: showPlansProp, onShowPlansChange, showPerUserLimits: showPerUserLimitsProp, onShowPerUserLimitsChange, showSharedCredits: showSharedCreditsProp, onShowSharedCreditsChange, onEntitlementChange, }?: {
     embedded?: boolean;
     /** Controlled "plans" sub-view flag. When provided, the host (settings
      *  wrapper) owns it so it can hide the sub-nav + show the Plans breadcrumb. */
@@ -1431,6 +1462,14 @@ declare function BillingContent({ embedded, showPlans: showPlansProp, onShowPlan
      *  workspace is in an organization. */
     showSharedCredits?: boolean;
     onShowSharedCreditsChange?: (open: boolean) => void;
+    /** Called once the current plan has loaded, and again when it changes:
+     *  billing's `entitlement` (null from servers without it) and whether the
+     *  workspace gets paid features. A workspace spending a sponsor's shared
+     *  credits is `paid` on its free plan; gate features on this, not the plan. */
+    onEntitlementChange?: (state: {
+        entitlement: BillingEntitlement | null;
+        paid: boolean;
+    }) => void;
 }): react__default.JSX.Element;
 
 /**
@@ -2082,18 +2121,63 @@ declare function formatPoolSplit(split: {
 }): string;
 /** "20% · 200 credits this cycle", or "200 credits this cycle" for a fixed share. */
 declare function describeAllowance(member: Pick<CreditPoolMember, "mode" | "value" | "allowance">): string;
+/**
+ * When a share stops on its own, as the Ends field picks it. `never` is
+ * today's behaviour: the share renews every cycle until it is removed.
+ */
+type PoolExpiryChoice = {
+    kind: "never";
+} | {
+    kind: "month";
+} | {
+    kind: "months";
+    months: number;
+} | {
+    kind: "year";
+}
+/** A local calendar day, `YYYY-MM-DD` (what `<input type="date">` gives). */
+ | {
+    kind: "date";
+    date: string;
+};
+declare const POOL_EXPIRY_MAX_MONTHS = 120;
+/** A local calendar day as `YYYY-MM-DD`. */
+declare function toLocalDateInput(date: Date): string;
+/** The earliest day the date picker allows: tomorrow, in local time. */
+declare function minPoolEndDate(now?: Date): string;
+type PoolEndsAtResult = {
+    ok: true;
+    value: string | null;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * The `endsAt` to send for a choice, as an ISO string, or `null` for Never.
+ * Months and a year count from `now`; a date is the start of that day in the
+ * admin's local time and must be after today.
+ */
+declare function poolEndsAtFrom(choice: PoolExpiryChoice, now?: Date): PoolEndsAtResult;
+/** The Ends field's starting choice for a share: Never, or its end date's day. */
+declare function expiryChoiceFor(member: Pick<CreditPoolMember, "endsAt"> | null | undefined): PoolExpiryChoice;
+/** When a share ends: "Mar 1, 2027", or "Never" when it runs until removed. */
+declare function formatPoolEndsAt(endsAt: string | null | undefined): string;
+/** The member banner's line on when sharing stops: "Sharing ends on Mar 1, 2027." or "Sharing ends: Never." */
+declare function sharedPoolEndsText(pool: Pick<SharedPoolBalance, "endsAt">): string;
+/** Whether the allowance starts again at `cycleEnd`: not when the share has ended by then. */
+declare function poolRenewsAtCycleEnd(pool: Pick<SharedPoolBalance, "endsAt" | "cycleEnd">): boolean;
 /** The other workspace's name, or a stand-in when it could not be resolved. */
 declare function poolWorkspaceName(name: string | null | undefined): string;
 /** The member's Billing banner: "Credits shared by Agency: 80 of 200 left this cycle". */
 declare function sharedPoolBannerText(pool: Pick<SharedPoolBalance, "sponsorName" | "allowance" | "remaining">): string;
 /**
- * The line under the member's banner when its own credits could not be spent
- * with the pool's. Billing now spends them first (see `ownCreditsFirstText`);
- * kept for hosts that still show it.
+ * Was the line saying a member's own credits were paused while it used the
+ * pool's. Billing spends them first, so it now answers `ownCreditsFirstText`
+ * for hosts that still call it.
  *
  * @deprecated Use `ownCreditsFirstText`.
  */
-declare function pausedOwnCreditsText(pool: Pick<SharedPoolBalance, "ownCredits">): string;
+declare function pausedOwnCreditsText(_pool?: Pick<SharedPoolBalance, "ownCredits">): string;
 /** The line under the member's banner: whose credits a job spends, in order. */
 declare function ownCreditsFirstText(): string;
 interface CreditsMeter {
@@ -2151,6 +2235,78 @@ declare function poolErrorMessage(failure: unknown): string | null;
  */
 declare function SharedCreditsView(): react.JSX.Element;
 
+/**
+ * Whether a workspace gets paid features, and why. Billing reports it at the
+ * top level of the current-subscription answer, beside `data` (200:
+ * `{ success, data, entitlement }`; 404: `{ error, entitlement }`), and
+ * leaves the plan as it is: a workspace spending another's shared credits (a
+ * "sponsored" workspace) still shows the free plan, with
+ * `entitlement.source: 'pool'`.
+ *
+ * So the plan — and every billing action: Upgrade, Cancel downgrade, Buy
+ * credits — stays decided by the plan's amount, and only features are gated
+ * on `entitlement.paid`. Billing servers from before entitlement send none;
+ * then a workspace is paid exactly when its plan is, as before.
+ */
+/** `entitlement` as billing sends it, or null when it is absent or malformed. */
+declare function parseBillingEntitlement(value: unknown): BillingEntitlement | null;
+/**
+ * The `entitlement` of a current-subscription answer: `body.entitlement`,
+ * never `body.data.entitlement` (`data` is the subscription).
+ */
+declare function entitlementFromBody(body: unknown): BillingEntitlement | null;
+/**
+ * The entitlement a failed read carries: billing's 404 for a workspace with
+ * no subscription of its own still says whether a pool entitles it. The body
+ * is looked for where hosts keep it — the failure itself, `body`, `data`
+ * (`UserFacingError`), `response.data` (axios) and `cause` — to a shallow
+ * depth. Null when there is none.
+ */
+declare function entitlementFromFailure(failure: unknown): BillingEntitlement | null;
+/** Paid by the workspace's own plan: what Buy credits and the plan actions go by. */
+declare function isPaidPlan(subscription: Pick<BillingSubscription, "plan"> | null | undefined): boolean;
+/**
+ * Whether the workspace gets paid features: `entitlement.paid` when billing
+ * sent one, else its own plan being paid (servers from before entitlement).
+ */
+declare function hasPaidFeatures({ entitlement, subscription, }: {
+    entitlement: BillingEntitlement | null | undefined;
+    subscription: Pick<BillingSubscription, "plan"> | null | undefined;
+}): boolean;
+/** A workspace spending another's shared credits, by its entitlement. */
+declare function isSponsoredEntitlement(entitlement: BillingEntitlement | null | undefined): entitlement is BillingEntitlement & {
+    source: "pool";
+};
+/** "Credits shared by Agency." plus " Sharing ends on Mar 1, 2027." when it ends on its own. */
+declare function sponsoredCreditsText(entitlement: Pick<BillingEntitlement, "sponsorName" | "endsAt">): string;
+interface CurrentPlanState {
+    /** The workspace's own subscription; null without one. */
+    subscription: BillingSubscription | null;
+    /** Null when billing sent none (servers from before entitlement). */
+    entitlement: BillingEntitlement | null;
+    /** Gate features on this; see `hasPaidFeatures`. */
+    paid: boolean;
+}
+/**
+ * Read the current plan and its entitlement through the host's
+ * `fetchCurrentPlan`. A failure that carries an entitlement — billing's 404
+ * for a sponsored workspace with no subscription of its own — is not an
+ * error: it answers no subscription with that entitlement. Any other failure
+ * is thrown, as before.
+ */
+declare function loadCurrentPlan(fetchCurrentPlan: () => Promise<SubscriptionResponse>): Promise<CurrentPlanState>;
+
+/**
+ * `loadCurrentPlan` as a hook, for a host gating features on `paid`. Reloads
+ * when `key` (e.g. the workspace id) changes; `fetchCurrentPlan` may be a new
+ * function every render. `state` is null while loading, after a failure, and
+ * while `key` is null.
+ */
+declare function useBillingEntitlement(fetchCurrentPlan: (() => Promise<SubscriptionResponse>) | null | undefined, key: string | null | undefined): {
+    state: CurrentPlanState | null;
+    loading: boolean;
+};
+
 type CreditPoolMemberModalProps = {
     kind: "add";
     /** Workspaces credits can be shared with. */
@@ -2278,4 +2434,4 @@ interface AppSettingsRowProps {
 }
 declare function AppSettingsRow({ title, description, summary, href, onClick, disabled, disabledReason, ariaLabel, trailing }: AppSettingsRowProps): react.JSX.Element;
 
-export { APP_KEYS, type AddCreditPoolMemberInput, AdministrationOverview, type AdministrationOverviewProps, type AdministrativeNavigationOptions, type ApiToken, type AppKey, AppSettingsHeader, type AppSettingsHeaderProps, AppSettingsPage, type AppSettingsPageProps, AppSettingsRow, type AppSettingsRowProps, AppSettingsSection, type AppSettingsSectionProps, type AvailableCreditsResponse, BillingContent, type BillingEventPayload, type BillingProduct, type BillingSubscription, BuyCreditsModal, type BuyCreditsPayload, type BuyCreditsResponse, ConfirmDeleteModal, ConfirmLeaveModal, type ConnectedApp, ConnectedAppsContent, type CreatedToken, type CreditCycleUnit, type CreditLimitValidation, type CreditPoolCandidate, type CreditPoolFormerMember, type CreditPoolMember, CreditPoolMemberModal, type CreditPoolMemberModalProps, type CreditPoolMemberStatus, type CreditPoolMode, type CreditPoolResponse, type CreditsMeter, type CustomCreditInfo, type CustomCreditResponse, DEFAULT_PERMISSIONS, DEFAULT_USER_LANGUAGE, ExportDateModal, InviteUpdateModal, type InvoicePdfResponse, type MemberCreditLimit, MemberCreditLimitModal, type MemberCreditLimitRow, type MemberCreditLimitSource, type MemberCreditLimitsResponse, MemberListFrame, type MemberListFrameProps, type MemberListTab, MemberListToolbar, type MemberListToolbarProps, type MemberPermissionsPayload, OrganizationContent, type OrganizationData, type OrganizationDetails, OrganizationIntegrationsContent, type OrganizationInvite, type OrganizationJoinRequest, type OrganizationJoinableWorkspace, type OrganizationMember, OrganizationMemberModal, type OrganizationMemberModalProps, type OrganizationMemberRole, OrganizationModal, OrganizationPicker, type OrganizationPickerItem, type OrganizationPickerProps, type OrganizationPickerType, type OrganizationView, type OrganizationWorkspaceItem, POOL_ERROR_CODES, POOL_NOTE_MAX_LENGTH, PerUserLimitsView, type PoolErrorCode, type PoolValueValidation, type Price, type PriceMetadata, type ProductsResponse, ProfileAvatar, ProfileTab, REMOVE_REASON_MAX_LENGTH, ReferralTab, RemovePoolMemberModal, type RemovePoolMemberModalProps, SCOPE_LABELS, ScopeHeader, type ScopeHeaderProps, type ServiceItem, type SettingsAdapters, SettingsAdaptersProvider, type SettingsApiAdapter, type SettingsAuthAdapter, type SettingsAuthUser, SettingsContent, type SettingsContentProps, type SettingsImageUploadAdapter, type SettingsIntegrationsAdapter, type SettingsNavigationAdapter, type SettingsOrganizationAdapter, type SettingsOrganizationCreateOptions, type SettingsOrganizationCurrent, type SettingsOrganizationJoinableItem, type SettingsOrganizationListItem, type SettingsOrganizationType, type SettingsScope, type SettingsTab, type SettingsToastAdapter, SettingsTooltip, type SettingsTooltipPlacement, type SettingsTooltipProps, type SettingsWorkspaceAdapter, type SettingsWorkspaceCurrent, type SettingsWorkspaceListItem, SharedCreditsView, type SharedPoolBalance, SiconKey, type StoreItem, type SubscriptionPlan, type SubscriptionResponse, TAB_DESCRIPTIONS, TAB_LABELS, TAB_SCOPE, TAB_TO_URL, type TeamMember, TeamsContent, type TokenExpiry, TokensContent, URL_TO_TAB, USER_LANGUAGES, type UpdateCreditPoolMemberInput, type UpdateSubscriptionPayload, type UpdateSubscriptionResponse, type UsageHistoryItem, type UsageHistoryResponse, type UserLanguage, type UserPermissions, WORKSPACE_LIST_PAGE_SIZE, type WorkspaceData, WorkspaceGeneralTab, type WorkspaceGeneralTabProps, type WorkspaceInvite, type WorkspaceListOrganization, WorkspaceListTab, type WorkspaceMember, WorkspaceModal, type WorkspaceOrganization, type WorkspaceOrganizationRequest, WorkspacePicker, type WorkspacePickerGroup, type WorkspacePickerItem, type WorkspacePickerProps, WorkspaceTab, type WorkspaceUsageResponse, belowUsageReason, canShowSharedCredits, cleanCreditLimitInput, cleanPoolValueInput, countLabel, creditCycleUnit, creditsMeter, deriveWorkspaceInvitePermission, describeAllowance, describeDefaultLimit, describeMemberLimit, findBillingError, findPoolError, formatCreditLimit, formatCredits, formatPoolSplit, groupWorkspaceList, isLimitBelowUsage, joinMembersWithLimits, lastUsedLabel, limitBelowUsageUsed, limitSourceLabel, loadWorkspaceOrganization, memberRoleUpdate, minimumCreditLimit, ownCreditsFirstText, pausedOwnCreditsText, poolErrorMessage, poolWorkspaceName, readSettingsCaller, rememberSettingsCaller, resolveSettingsTabFromPath, roundCredits, settingsReturnTarget, sharedPoolBannerText, useSettingsAdapters, useWorkspaceInvitePermission, useWorkspaceOrganization, usedByNamesFrom, usedByWorkspaceKey, userLanguageLabel, validateCreditLimitInput, validateDefaultCreditLimitInput, validatePoolText, validatePoolValue };
+export { APP_KEYS, type AddCreditPoolMemberInput, AdministrationOverview, type AdministrationOverviewProps, type AdministrativeNavigationOptions, type ApiToken, type AppKey, AppSettingsHeader, type AppSettingsHeaderProps, AppSettingsPage, type AppSettingsPageProps, AppSettingsRow, type AppSettingsRowProps, AppSettingsSection, type AppSettingsSectionProps, type AvailableCreditsResponse, BillingContent, type BillingEntitlement, type BillingEventPayload, type BillingProduct, type BillingSubscription, BuyCreditsModal, type BuyCreditsPayload, type BuyCreditsResponse, ConfirmDeleteModal, ConfirmLeaveModal, type ConnectedApp, ConnectedAppsContent, type CreatedToken, type CreditCycleUnit, type CreditLimitValidation, type CreditPoolCandidate, type CreditPoolFormerMember, type CreditPoolMember, CreditPoolMemberModal, type CreditPoolMemberModalProps, type CreditPoolMemberStatus, type CreditPoolMode, type CreditPoolResponse, type CreditsMeter, type CurrentPlanState, type CustomCreditInfo, type CustomCreditResponse, DEFAULT_PERMISSIONS, DEFAULT_USER_LANGUAGE, ExportDateModal, InviteUpdateModal, type InvoicePdfResponse, type MemberCreditLimit, MemberCreditLimitModal, type MemberCreditLimitRow, type MemberCreditLimitSource, type MemberCreditLimitsResponse, MemberListFrame, type MemberListFrameProps, type MemberListTab, MemberListToolbar, type MemberListToolbarProps, type MemberPermissionsPayload, OrganizationContent, type OrganizationData, type OrganizationDetails, OrganizationIntegrationsContent, type OrganizationInvite, type OrganizationJoinRequest, type OrganizationJoinableWorkspace, type OrganizationMember, OrganizationMemberModal, type OrganizationMemberModalProps, type OrganizationMemberRole, OrganizationModal, OrganizationPicker, type OrganizationPickerItem, type OrganizationPickerProps, type OrganizationPickerType, type OrganizationView, type OrganizationWorkspaceItem, POOL_ERROR_CODES, POOL_EXPIRY_MAX_MONTHS, POOL_NOTE_MAX_LENGTH, PerUserLimitsView, type PoolEndsAtResult, type PoolErrorCode, type PoolExpiryChoice, type PoolValueValidation, type Price, type PriceMetadata, type ProductsResponse, ProfileAvatar, ProfileTab, REMOVE_REASON_MAX_LENGTH, ReferralTab, RemovePoolMemberModal, type RemovePoolMemberModalProps, SCOPE_LABELS, ScopeHeader, type ScopeHeaderProps, type ServiceItem, type SettingsAdapters, SettingsAdaptersProvider, type SettingsApiAdapter, type SettingsAuthAdapter, type SettingsAuthUser, SettingsContent, type SettingsContentProps, type SettingsImageUploadAdapter, type SettingsIntegrationsAdapter, type SettingsNavigationAdapter, type SettingsOrganizationAdapter, type SettingsOrganizationCreateOptions, type SettingsOrganizationCurrent, type SettingsOrganizationJoinableItem, type SettingsOrganizationListItem, type SettingsOrganizationType, type SettingsScope, type SettingsTab, type SettingsToastAdapter, SettingsTooltip, type SettingsTooltipPlacement, type SettingsTooltipProps, type SettingsWorkspaceAdapter, type SettingsWorkspaceCurrent, type SettingsWorkspaceListItem, SharedCreditsView, type SharedPoolBalance, SiconKey, type StoreItem, type SubscriptionPlan, type SubscriptionResponse, TAB_DESCRIPTIONS, TAB_LABELS, TAB_SCOPE, TAB_TO_URL, type TeamMember, TeamsContent, type TokenExpiry, TokensContent, URL_TO_TAB, USER_LANGUAGES, type UpdateCreditPoolMemberInput, type UpdateSubscriptionPayload, type UpdateSubscriptionResponse, type UsageHistoryItem, type UsageHistoryResponse, type UserLanguage, type UserPermissions, WORKSPACE_LIST_PAGE_SIZE, type WorkspaceData, WorkspaceGeneralTab, type WorkspaceGeneralTabProps, type WorkspaceInvite, type WorkspaceListOrganization, WorkspaceListTab, type WorkspaceMember, WorkspaceModal, type WorkspaceOrganization, type WorkspaceOrganizationRequest, WorkspacePicker, type WorkspacePickerGroup, type WorkspacePickerItem, type WorkspacePickerProps, WorkspaceTab, type WorkspaceUsageResponse, belowUsageReason, canShowSharedCredits, cleanCreditLimitInput, cleanPoolValueInput, countLabel, creditCycleUnit, creditsMeter, deriveWorkspaceInvitePermission, describeAllowance, describeDefaultLimit, describeMemberLimit, entitlementFromBody, entitlementFromFailure, expiryChoiceFor, findBillingError, findPoolError, formatCreditLimit, formatCredits, formatPoolEndsAt, formatPoolSplit, groupWorkspaceList, hasPaidFeatures, isLimitBelowUsage, isPaidPlan, isSponsoredEntitlement, joinMembersWithLimits, lastUsedLabel, limitBelowUsageUsed, limitSourceLabel, loadCurrentPlan, loadWorkspaceOrganization, memberRoleUpdate, minPoolEndDate, minimumCreditLimit, ownCreditsFirstText, parseBillingEntitlement, pausedOwnCreditsText, poolEndsAtFrom, poolErrorMessage, poolRenewsAtCycleEnd, poolWorkspaceName, readSettingsCaller, rememberSettingsCaller, resolveSettingsTabFromPath, roundCredits, settingsReturnTarget, sharedPoolBannerText, sharedPoolEndsText, sponsoredCreditsText, toLocalDateInput, useBillingEntitlement, useSettingsAdapters, useWorkspaceInvitePermission, useWorkspaceOrganization, usedByNamesFrom, usedByWorkspaceKey, userLanguageLabel, validateCreditLimitInput, validateDefaultCreditLimitInput, validatePoolText, validatePoolValue };