@streamoid/settings 0.9.1 → 0.10.0

package/README.md

@@ -159,6 +159,18 @@ usually what you want.
 
 See [`src/adapters.ts`](src/adapters.ts) for full type definitions.
 
+### Optional billing features
+
+Billing hides an entry whose adapter method is absent:
+
+- **Per-user usage limits:** `api.fetchMemberCreditLimits` (plus
+  `setMemberCreditLimit`, `removeMemberCreditLimit`, `setDefaultCreditLimit`).
+- **Credit allocations:** `api.fetchCreditAllocations`, and the workspace must
+  be in an organization. `createCreditAllocation`, `updateCreditAllocation`,
+  `cancelCreditAllocation`, `fetchCreditTransfers` and
+  `fetchAllocationTargets` light up the rest. Only organization admins
+  change allocations; the server says so with `canManage`.
+
 ## Status
 
 - **0.1.0** — Adapter surface and package scaffold. Tab content lands in

package/dist/index.d.mts

@@ -832,6 +832,102 @@ interface MemberCreditLimitsResponse {
     /** Only members with an override or with usage; the rest follow the default. */
     users: MemberCreditLimit[];
 }
+type CreditAllocationMode = "fixed" | "percent";
+type CreditAllocationStatus = "active" | "canceled";
+/**
+ * A workspace sending part of its credits to another workspace of its
+ * organization: once when created, and again out of every renewal grant while
+ * `recurring`. Workspace ids are the host's workspace ids (`*WorkspaceKey`).
+ */
+interface CreditAllocation {
+    _id: string;
+    /** The sponsor (source) workspace. */
+    sourceWorkspaceKey: string;
+    sourceWorkspaceName?: string | null;
+    /** The receiving (target) workspace. */
+    targetWorkspaceKey: string;
+    targetWorkspaceName?: string | null;
+    mode: CreditAllocationMode;
+    /** Credits for `fixed`; a share of each grant, (0–100], for `percent`. */
+    value: number;
+    recurring: boolean;
+    status: CreditAllocationStatus;
+    /** This allocation moved the target off the free plan, so cancelling moves it back. */
+    targetPlanChanged?: boolean;
+    /**
+     * The first move, from the source's balance, when the allocation was made.
+     * `failed` means the allocation is active (renewals still split) but those
+     * first credits did NOT move.
+     */
+    initialTransfer?: {
+        status: "done" | "failed";
+        credits: number;
+        error?: string;
+    };
+    note?: string;
+    requestedBy?: string;
+    createdBy?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    canceledAt?: string;
+    canceledBy?: string;
+    cancelReason?: string;
+}
+interface CreditAllocationsResponse {
+    /** Allocations this workspace sponsors, canceled ones included, newest first. */
+    giving: CreditAllocation[];
+    /** Allocations sponsoring this workspace (at most one active). */
+    receiving: CreditAllocation[];
+    /** The viewer may create, change and cancel (an admin of the organization). */
+    canManage: boolean;
+}
+interface CreateCreditAllocationInput {
+    targetWorkspaceId: string;
+    mode: CreditAllocationMode;
+    value: number;
+    recurring: boolean;
+    /** Why — required, at most 500 characters. */
+    note: string;
+}
+type UpdateCreditAllocationInput = {
+    mode: CreditAllocationMode;
+    value: number;
+    recurring?: boolean;
+} | {
+    recurring: boolean;
+};
+interface CancelCreditAllocationResult {
+    allocation: CreditAllocation;
+    /** The target was moved back to the free plan. */
+    targetMovedToFree: boolean;
+    /** Why billing left the target on its plan on purpose (bought its own, already on free). */
+    reason?: string;
+    /** Set when moving the target back to free failed; the allocation is canceled anyway. */
+    error?: string;
+}
+interface CreditTransfer {
+    id: string;
+    direction: "sent" | "received";
+    credits: number;
+    createdAt: string | null;
+    expiresAt?: string | null;
+    allocationId: string | null;
+    kind: "initial" | "renewal";
+    counterpartWorkspaceId: string | null;
+    counterpartWorkspaceName: string | null;
+}
+interface CreditTransfersPage {
+    transfers: CreditTransfer[];
+    page: number;
+    limit: number;
+    total: number;
+}
+/** A workspace credits can be allocated to (another workspace of the organization). */
+interface CreditAllocationTarget {
+    id: string;
+    name: string;
+    imageUrl?: string;
+}
 /**
  * The API adapter is split into three concern areas (billing / teams /
  * tokens) but kept flat to match the original spec. Methods are grouped with
@@ -967,6 +1063,27 @@ interface SettingsApiAdapter {
     /** Set the workspace default per-member limit; `null` means Unlimited.
      *  Applies to members without their own override. Throws on error. */
     setDefaultCreditLimit?: (limit: number | null) => Promise<void>;
+    /**
+     * What this workspace gives to and receives from other workspaces of its
+     * organization. When omitted, Billing hides the "Credit allocations" entry.
+     */
+    fetchCreditAllocations?: () => Promise<CreditAllocationsResponse>;
+    /** Organization admins only. Moves the first share now. Rejects with the
+     *  billing `code` (`INSUFFICIENT_CREDITS`, `ALLOCATION_NOT_ALLOWED`,
+     *  `SOURCE_ON_FREE_PLAN`, `TARGET_PLAN_CHANGE_FAILED`) on the error body. */
+    createCreditAllocation?: (input: CreateCreditAllocationInput) => Promise<CreditAllocation>;
+    /** Change the split and/or repeat; applies from the next renewal. */
+    updateCreditAllocation?: (allocationId: string, patch: UpdateCreditAllocationInput) => Promise<CreditAllocation>;
+    /** Stop an allocation. Resolves even when the target could not be moved
+     *  back to free — check `targetMovedToFree` / `error`. */
+    cancelCreditAllocation?: (allocationId: string, reason: string) => Promise<CancelCreditAllocationResult>;
+    /** Transfers this workspace sent or received, newest first. */
+    fetchCreditTransfers?: (input: {
+        page: number;
+        limit: number;
+    }) => Promise<CreditTransfersPage>;
+    /** Workspaces this one may allocate to: its organization's others. */
+    fetchAllocationTargets?: () => Promise<CreditAllocationTarget[]>;
     fetchTokens: (params?: {
         showRevoked?: boolean;
     }) => Promise<ApiToken[]>;
@@ -1284,7 +1401,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, }?: {
+declare function BillingContent({ embedded, showPlans: showPlansProp, onShowPlansChange, showPerUserLimits: showPerUserLimitsProp, onShowPerUserLimitsChange, showCreditAllocations: showCreditAllocationsProp, onShowCreditAllocationsChange, }?: {
     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. */
@@ -1294,6 +1411,11 @@ declare function BillingContent({ embedded, showPlans: showPlansProp, onShowPlan
      *  Only reachable when `api.fetchMemberCreditLimits` exists. */
     showPerUserLimits?: boolean;
     onShowPerUserLimitsChange?: (open: boolean) => void;
+    /** Controlled "credit allocations" sub-view flag; same contract as
+     *  `showPlans`. Only reachable when `api.fetchCreditAllocations` exists and
+     *  the workspace is in an organization. */
+    showCreditAllocations?: boolean;
+    onShowCreditAllocationsChange?: (open: boolean) => void;
 }): react__default.JSX.Element;
 
 /**
@@ -1850,6 +1972,13 @@ declare function isLimitBelowUsage(failure: unknown): boolean;
  * spent more since. `null` when the failure is not one, or carries no figure.
  */
 declare function limitBelowUsageUsed(failure: unknown): number | null;
+/**
+ * The error object carrying one of the billing `codes`, wherever the failure
+ * keeps it. `UserFacingError` rewrites `err.code` to a category, so the
+ * original body is searched: `code`, `error.*`, `body.*`, `data.*`,
+ * `publicError.*` and `cause`, to a shallow depth. `null` when none matches.
+ */
+declare function findBillingError(failure: unknown, codes: readonly string[]): Record<string, unknown> | null;
 
 /** Billing sub-view: per-member credit limits for the current billing cycle. */
 declare function PerUserLimitsView(): react.JSX.Element;
@@ -1893,6 +2022,141 @@ interface MemberCreditLimitModalProps {
 /** A fixed number of credits per cycle, or unlimited — for one member or the workspace default. */
 declare function MemberCreditLimitModal({ open, title, description, subject, resetKey, used, initialLimit, isSet, unit, onSave, onRemove, removeLabel, removeHint, saveSuccessMessage, removeSuccessMessage, onClose, onSaved, onStale, }: MemberCreditLimitModalProps): react.JSX.Element | null;
 
+/**
+ * Credit allocation rules and copy, kept out of the components so a host can
+ * test them. The server (billing, behind unified-backend) is the authority;
+ * these only stop an obviously bad request and say clearly what happened.
+ */
+declare const ALLOCATION_NOTE_MAX_LENGTH = 500;
+declare const CANCEL_REASON_MAX_LENGTH = 500;
+/**
+ * Whether Billing offers credit allocations: the host implements them, and the
+ * workspace is in an organization (allocations move credits between one
+ * organization's workspaces, so a personal workspace has nowhere to send them).
+ */
+declare function canShowCreditAllocations(api: Pick<SettingsApiAdapter, "fetchCreditAllocations">, workspace: Pick<SettingsWorkspaceCurrent, "organizationId"> | null | undefined, organization: Pick<SettingsOrganizationCurrent, "id"> | null | undefined): boolean;
+type AllocationValueValidation = {
+    ok: true;
+    value: number;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Digits and one `.` — what the value input keeps as the user types. */
+declare function cleanAllocationValueInput(raw: string): string;
+/**
+ * A split value as billing accepts it: > 0, at most two decimals, and at most
+ * 100 for a percent. A fixed share over `balance` (when known) is refused too —
+ * the first share moves from the balance right away.
+ */
+declare function validateAllocationValue(mode: CreditAllocationMode, raw: string, balance?: number | null): AllocationValueValidation;
+/** A required note or reason: trimmed, non-empty, at most `max` characters. */
+declare function validateAllocationText(raw: string, max: number): {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** `fixed 500` → "500 credits"; `percent 20` → "20%". */
+declare function formatAllocationSplit(split: {
+    mode: CreditAllocationMode;
+    value: number;
+}): string;
+/** "Every renewal" or "Once". */
+declare function formatAllocationRepeat(recurring: boolean): string;
+/** "500 credits every renewal", "20% of each renewal", "500 credits once". */
+declare function describeAllocation(allocation: Pick<CreditAllocation, "mode" | "value" | "recurring">): string;
+/** The other workspace's name, or a stand-in when it could not be resolved. */
+declare function allocationWorkspaceName(name: string | null | undefined): string;
+/**
+ * Why the first transfer did not happen, when it failed. The allocation was
+ * still made — so without this an admin would assume the credits moved.
+ */
+declare function initialTransferWarning(allocation: Pick<CreditAllocation, "initialTransfer">): string | null;
+/** "Sent 500 credits at setup", when the first transfer went through. */
+declare function initialTransferSummary(allocation: Pick<CreditAllocation, "initialTransfer">): string | null;
+/**
+ * What still needs doing after a cancel, or `null` when nothing does.
+ *
+ * Billing cancels the allocation even when moving the target back to free
+ * fails (`error`). A target this allocation moved off free (`targetPlanChanged`)
+ * that was not moved back stays on the $0 Custom plan, without its free monthly
+ * credits. No customer-facing action moves a workspace to free immediately, so
+ * the way out is Streamoid support. When billing left the target's plan on
+ * purpose it says why (`reason`: it bought a plan of its own, or is already on
+ * free), and nothing needs fixing; nor does a target that was never moved.
+ */
+declare function cancelOutcomeWarning(result: Pick<CancelCreditAllocationResult, "targetMovedToFree" | "reason" | "error"> & {
+    allocation?: Pick<CreditAllocation, "targetPlanChanged"> | null;
+}, targetName: string): string | null;
+/**
+ * The toast after a cancel that needs nothing fixed: plain, or saying why
+ * billing left a target this allocation had moved off free on its plan.
+ */
+declare function cancelOutcomeSummary(result: Pick<CancelCreditAllocationResult, "targetMovedToFree" | "reason">, targetName: string): string;
+declare const ALLOCATION_ERROR_CODES: readonly ["INSUFFICIENT_CREDITS", "SOURCE_ON_FREE_PLAN", "ALLOCATION_NOT_ALLOWED", "TARGET_PLAN_CHANGE_FAILED"];
+type AllocationErrorCode = (typeof ALLOCATION_ERROR_CODES)[number];
+/** The billing allocation error in a failure: its code, details and server message. */
+declare function findAllocationError(failure: unknown): {
+    code: AllocationErrorCode;
+    details: Record<string, unknown>;
+    message: string | null;
+} | null;
+/**
+ * A plain sentence for a billing allocation refusal, or `null` when the
+ * failure is not one (the caller then falls back to its generic message).
+ */
+declare function allocationErrorMessage(failure: unknown): string | null;
+
+/**
+ * Billing sub-view: credits this workspace shares with, or receives from,
+ * other workspaces of its organization. Changes are for organization admins
+ * (`canManage` from the server); everyone else who reaches Billing reads.
+ */
+declare function CreditAllocationsView(): react.JSX.Element;
+
+type CreditAllocationModalProps = {
+    kind: "create";
+    /** Workspaces credits can go to. */
+    targets: CreditAllocationTarget[];
+    /** This workspace's available credits, when known: the first share comes out of it. */
+    balance: number | null;
+    onSave: (input: CreateCreditAllocationInput) => Promise<CreditAllocation>;
+    onClose: () => void;
+    /** After a save (or a failure that still left an allocation); the parent refetches. */
+    onSaved: () => void;
+} | {
+    kind: "edit";
+    allocation: CreditAllocation;
+    targetName: string;
+    onSave: (patch: UpdateCreditAllocationInput) => Promise<CreditAllocation>;
+    onClose: () => void;
+    onSaved: () => void;
+};
+/** Create an allocation, or change an active one's split and repeat. */
+declare function CreditAllocationModal(props: CreditAllocationModalProps): react.JSX.Element;
+
+interface CancelCreditAllocationModalProps {
+    allocation: CreditAllocation;
+    targetName: string;
+    onCancel: (reason: string) => Promise<CancelCreditAllocationResult>;
+    onClose: () => void;
+    /**
+     * After the allocation was canceled; the parent refetches. `planNotRestored`
+     * is true when the target was left on the Custom plan and someone has to fix it.
+     */
+    onCanceled: (result: {
+        planNotRestored: boolean;
+    }) => void;
+}
+/**
+ * Confirm a cancel with a reason. Billing cancels even when moving the target
+ * back to free fails; that outcome stays on screen (not a toast that can be
+ * missed) until the admin acknowledges it.
+ */
+declare function CancelCreditAllocationModal({ allocation, targetName, onCancel, onClose, onCanceled, }: CancelCreditAllocationModalProps): react.JSX.Element;
+
 declare function SettingsAdaptersProvider({ adapters, children, }: {
     adapters: SettingsAdapters;
     children: ReactNode;
@@ -1904,4 +2168,4 @@ declare function SettingsAdaptersProvider({ adapters, children, }: {
  */
 declare function useSettingsAdapters(): SettingsAdapters;
 
-export { APP_KEYS, type ApiToken, type AppKey, 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 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, PerUserLimitsView, type Price, type PriceMetadata, type ProductsResponse, ProfileAvatar, ProfileTab, ReferralTab, 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 SettingsOrganizationListItem, type SettingsOrganizationType, type SettingsScope, type SettingsTab, type SettingsToastAdapter, SettingsTooltip, type SettingsTooltipPlacement, type SettingsTooltipProps, type SettingsWorkspaceAdapter, type SettingsWorkspaceCurrent, type SettingsWorkspaceListItem, 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 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, cleanCreditLimitInput, countLabel, creditCycleUnit, describeDefaultLimit, describeMemberLimit, formatCreditLimit, formatCredits, groupWorkspaceList, isLimitBelowUsage, joinMembersWithLimits, lastUsedLabel, limitBelowUsageUsed, limitSourceLabel, loadWorkspaceOrganization, memberRoleUpdate, minimumCreditLimit, resolveSettingsTabFromPath, roundCredits, useSettingsAdapters, useWorkspaceOrganization, userLanguageLabel, validateCreditLimitInput, validateDefaultCreditLimitInput };
+export { ALLOCATION_ERROR_CODES, ALLOCATION_NOTE_MAX_LENGTH, APP_KEYS, type AllocationErrorCode, type AllocationValueValidation, type ApiToken, type AppKey, type AvailableCreditsResponse, BillingContent, type BillingEventPayload, type BillingProduct, type BillingSubscription, BuyCreditsModal, type BuyCreditsPayload, type BuyCreditsResponse, CANCEL_REASON_MAX_LENGTH, CancelCreditAllocationModal, type CancelCreditAllocationModalProps, type CancelCreditAllocationResult, ConfirmDeleteModal, ConfirmLeaveModal, type ConnectedApp, ConnectedAppsContent, type CreateCreditAllocationInput, type CreatedToken, type CreditAllocation, CreditAllocationModal, type CreditAllocationModalProps, type CreditAllocationMode, type CreditAllocationStatus, type CreditAllocationTarget, type CreditAllocationsResponse, CreditAllocationsView, type CreditCycleUnit, type CreditLimitValidation, type CreditTransfer, type CreditTransfersPage, 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, PerUserLimitsView, type Price, type PriceMetadata, type ProductsResponse, ProfileAvatar, ProfileTab, ReferralTab, 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 SettingsOrganizationListItem, type SettingsOrganizationType, type SettingsScope, type SettingsTab, type SettingsToastAdapter, SettingsTooltip, type SettingsTooltipPlacement, type SettingsTooltipProps, type SettingsWorkspaceAdapter, type SettingsWorkspaceCurrent, type SettingsWorkspaceListItem, 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 UpdateCreditAllocationInput, 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, allocationErrorMessage, allocationWorkspaceName, belowUsageReason, canShowCreditAllocations, cancelOutcomeSummary, cancelOutcomeWarning, cleanAllocationValueInput, cleanCreditLimitInput, countLabel, creditCycleUnit, describeAllocation, describeDefaultLimit, describeMemberLimit, findAllocationError, findBillingError, formatAllocationRepeat, formatAllocationSplit, formatCreditLimit, formatCredits, groupWorkspaceList, initialTransferSummary, initialTransferWarning, isLimitBelowUsage, joinMembersWithLimits, lastUsedLabel, limitBelowUsageUsed, limitSourceLabel, loadWorkspaceOrganization, memberRoleUpdate, minimumCreditLimit, resolveSettingsTabFromPath, roundCredits, useSettingsAdapters, useWorkspaceOrganization, userLanguageLabel, validateAllocationText, validateAllocationValue, validateCreditLimitInput, validateDefaultCreditLimitInput };

package/dist/index.d.ts

@@ -832,6 +832,102 @@ interface MemberCreditLimitsResponse {
     /** Only members with an override or with usage; the rest follow the default. */
     users: MemberCreditLimit[];
 }
+type CreditAllocationMode = "fixed" | "percent";
+type CreditAllocationStatus = "active" | "canceled";
+/**
+ * A workspace sending part of its credits to another workspace of its
+ * organization: once when created, and again out of every renewal grant while
+ * `recurring`. Workspace ids are the host's workspace ids (`*WorkspaceKey`).
+ */
+interface CreditAllocation {
+    _id: string;
+    /** The sponsor (source) workspace. */
+    sourceWorkspaceKey: string;
+    sourceWorkspaceName?: string | null;
+    /** The receiving (target) workspace. */
+    targetWorkspaceKey: string;
+    targetWorkspaceName?: string | null;
+    mode: CreditAllocationMode;
+    /** Credits for `fixed`; a share of each grant, (0–100], for `percent`. */
+    value: number;
+    recurring: boolean;
+    status: CreditAllocationStatus;
+    /** This allocation moved the target off the free plan, so cancelling moves it back. */
+    targetPlanChanged?: boolean;
+    /**
+     * The first move, from the source's balance, when the allocation was made.
+     * `failed` means the allocation is active (renewals still split) but those
+     * first credits did NOT move.
+     */
+    initialTransfer?: {
+        status: "done" | "failed";
+        credits: number;
+        error?: string;
+    };
+    note?: string;
+    requestedBy?: string;
+    createdBy?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    canceledAt?: string;
+    canceledBy?: string;
+    cancelReason?: string;
+}
+interface CreditAllocationsResponse {
+    /** Allocations this workspace sponsors, canceled ones included, newest first. */
+    giving: CreditAllocation[];
+    /** Allocations sponsoring this workspace (at most one active). */
+    receiving: CreditAllocation[];
+    /** The viewer may create, change and cancel (an admin of the organization). */
+    canManage: boolean;
+}
+interface CreateCreditAllocationInput {
+    targetWorkspaceId: string;
+    mode: CreditAllocationMode;
+    value: number;
+    recurring: boolean;
+    /** Why — required, at most 500 characters. */
+    note: string;
+}
+type UpdateCreditAllocationInput = {
+    mode: CreditAllocationMode;
+    value: number;
+    recurring?: boolean;
+} | {
+    recurring: boolean;
+};
+interface CancelCreditAllocationResult {
+    allocation: CreditAllocation;
+    /** The target was moved back to the free plan. */
+    targetMovedToFree: boolean;
+    /** Why billing left the target on its plan on purpose (bought its own, already on free). */
+    reason?: string;
+    /** Set when moving the target back to free failed; the allocation is canceled anyway. */
+    error?: string;
+}
+interface CreditTransfer {
+    id: string;
+    direction: "sent" | "received";
+    credits: number;
+    createdAt: string | null;
+    expiresAt?: string | null;
+    allocationId: string | null;
+    kind: "initial" | "renewal";
+    counterpartWorkspaceId: string | null;
+    counterpartWorkspaceName: string | null;
+}
+interface CreditTransfersPage {
+    transfers: CreditTransfer[];
+    page: number;
+    limit: number;
+    total: number;
+}
+/** A workspace credits can be allocated to (another workspace of the organization). */
+interface CreditAllocationTarget {
+    id: string;
+    name: string;
+    imageUrl?: string;
+}
 /**
  * The API adapter is split into three concern areas (billing / teams /
  * tokens) but kept flat to match the original spec. Methods are grouped with
@@ -967,6 +1063,27 @@ interface SettingsApiAdapter {
     /** Set the workspace default per-member limit; `null` means Unlimited.
      *  Applies to members without their own override. Throws on error. */
     setDefaultCreditLimit?: (limit: number | null) => Promise<void>;
+    /**
+     * What this workspace gives to and receives from other workspaces of its
+     * organization. When omitted, Billing hides the "Credit allocations" entry.
+     */
+    fetchCreditAllocations?: () => Promise<CreditAllocationsResponse>;
+    /** Organization admins only. Moves the first share now. Rejects with the
+     *  billing `code` (`INSUFFICIENT_CREDITS`, `ALLOCATION_NOT_ALLOWED`,
+     *  `SOURCE_ON_FREE_PLAN`, `TARGET_PLAN_CHANGE_FAILED`) on the error body. */
+    createCreditAllocation?: (input: CreateCreditAllocationInput) => Promise<CreditAllocation>;
+    /** Change the split and/or repeat; applies from the next renewal. */
+    updateCreditAllocation?: (allocationId: string, patch: UpdateCreditAllocationInput) => Promise<CreditAllocation>;
+    /** Stop an allocation. Resolves even when the target could not be moved
+     *  back to free — check `targetMovedToFree` / `error`. */
+    cancelCreditAllocation?: (allocationId: string, reason: string) => Promise<CancelCreditAllocationResult>;
+    /** Transfers this workspace sent or received, newest first. */
+    fetchCreditTransfers?: (input: {
+        page: number;
+        limit: number;
+    }) => Promise<CreditTransfersPage>;
+    /** Workspaces this one may allocate to: its organization's others. */
+    fetchAllocationTargets?: () => Promise<CreditAllocationTarget[]>;
     fetchTokens: (params?: {
         showRevoked?: boolean;
     }) => Promise<ApiToken[]>;
@@ -1284,7 +1401,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, }?: {
+declare function BillingContent({ embedded, showPlans: showPlansProp, onShowPlansChange, showPerUserLimits: showPerUserLimitsProp, onShowPerUserLimitsChange, showCreditAllocations: showCreditAllocationsProp, onShowCreditAllocationsChange, }?: {
     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. */
@@ -1294,6 +1411,11 @@ declare function BillingContent({ embedded, showPlans: showPlansProp, onShowPlan
      *  Only reachable when `api.fetchMemberCreditLimits` exists. */
     showPerUserLimits?: boolean;
     onShowPerUserLimitsChange?: (open: boolean) => void;
+    /** Controlled "credit allocations" sub-view flag; same contract as
+     *  `showPlans`. Only reachable when `api.fetchCreditAllocations` exists and
+     *  the workspace is in an organization. */
+    showCreditAllocations?: boolean;
+    onShowCreditAllocationsChange?: (open: boolean) => void;
 }): react__default.JSX.Element;
 
 /**
@@ -1850,6 +1972,13 @@ declare function isLimitBelowUsage(failure: unknown): boolean;
  * spent more since. `null` when the failure is not one, or carries no figure.
  */
 declare function limitBelowUsageUsed(failure: unknown): number | null;
+/**
+ * The error object carrying one of the billing `codes`, wherever the failure
+ * keeps it. `UserFacingError` rewrites `err.code` to a category, so the
+ * original body is searched: `code`, `error.*`, `body.*`, `data.*`,
+ * `publicError.*` and `cause`, to a shallow depth. `null` when none matches.
+ */
+declare function findBillingError(failure: unknown, codes: readonly string[]): Record<string, unknown> | null;
 
 /** Billing sub-view: per-member credit limits for the current billing cycle. */
 declare function PerUserLimitsView(): react.JSX.Element;
@@ -1893,6 +2022,141 @@ interface MemberCreditLimitModalProps {
 /** A fixed number of credits per cycle, or unlimited — for one member or the workspace default. */
 declare function MemberCreditLimitModal({ open, title, description, subject, resetKey, used, initialLimit, isSet, unit, onSave, onRemove, removeLabel, removeHint, saveSuccessMessage, removeSuccessMessage, onClose, onSaved, onStale, }: MemberCreditLimitModalProps): react.JSX.Element | null;
 
+/**
+ * Credit allocation rules and copy, kept out of the components so a host can
+ * test them. The server (billing, behind unified-backend) is the authority;
+ * these only stop an obviously bad request and say clearly what happened.
+ */
+declare const ALLOCATION_NOTE_MAX_LENGTH = 500;
+declare const CANCEL_REASON_MAX_LENGTH = 500;
+/**
+ * Whether Billing offers credit allocations: the host implements them, and the
+ * workspace is in an organization (allocations move credits between one
+ * organization's workspaces, so a personal workspace has nowhere to send them).
+ */
+declare function canShowCreditAllocations(api: Pick<SettingsApiAdapter, "fetchCreditAllocations">, workspace: Pick<SettingsWorkspaceCurrent, "organizationId"> | null | undefined, organization: Pick<SettingsOrganizationCurrent, "id"> | null | undefined): boolean;
+type AllocationValueValidation = {
+    ok: true;
+    value: number;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Digits and one `.` — what the value input keeps as the user types. */
+declare function cleanAllocationValueInput(raw: string): string;
+/**
+ * A split value as billing accepts it: > 0, at most two decimals, and at most
+ * 100 for a percent. A fixed share over `balance` (when known) is refused too —
+ * the first share moves from the balance right away.
+ */
+declare function validateAllocationValue(mode: CreditAllocationMode, raw: string, balance?: number | null): AllocationValueValidation;
+/** A required note or reason: trimmed, non-empty, at most `max` characters. */
+declare function validateAllocationText(raw: string, max: number): {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** `fixed 500` → "500 credits"; `percent 20` → "20%". */
+declare function formatAllocationSplit(split: {
+    mode: CreditAllocationMode;
+    value: number;
+}): string;
+/** "Every renewal" or "Once". */
+declare function formatAllocationRepeat(recurring: boolean): string;
+/** "500 credits every renewal", "20% of each renewal", "500 credits once". */
+declare function describeAllocation(allocation: Pick<CreditAllocation, "mode" | "value" | "recurring">): string;
+/** The other workspace's name, or a stand-in when it could not be resolved. */
+declare function allocationWorkspaceName(name: string | null | undefined): string;
+/**
+ * Why the first transfer did not happen, when it failed. The allocation was
+ * still made — so without this an admin would assume the credits moved.
+ */
+declare function initialTransferWarning(allocation: Pick<CreditAllocation, "initialTransfer">): string | null;
+/** "Sent 500 credits at setup", when the first transfer went through. */
+declare function initialTransferSummary(allocation: Pick<CreditAllocation, "initialTransfer">): string | null;
+/**
+ * What still needs doing after a cancel, or `null` when nothing does.
+ *
+ * Billing cancels the allocation even when moving the target back to free
+ * fails (`error`). A target this allocation moved off free (`targetPlanChanged`)
+ * that was not moved back stays on the $0 Custom plan, without its free monthly
+ * credits. No customer-facing action moves a workspace to free immediately, so
+ * the way out is Streamoid support. When billing left the target's plan on
+ * purpose it says why (`reason`: it bought a plan of its own, or is already on
+ * free), and nothing needs fixing; nor does a target that was never moved.
+ */
+declare function cancelOutcomeWarning(result: Pick<CancelCreditAllocationResult, "targetMovedToFree" | "reason" | "error"> & {
+    allocation?: Pick<CreditAllocation, "targetPlanChanged"> | null;
+}, targetName: string): string | null;
+/**
+ * The toast after a cancel that needs nothing fixed: plain, or saying why
+ * billing left a target this allocation had moved off free on its plan.
+ */
+declare function cancelOutcomeSummary(result: Pick<CancelCreditAllocationResult, "targetMovedToFree" | "reason">, targetName: string): string;
+declare const ALLOCATION_ERROR_CODES: readonly ["INSUFFICIENT_CREDITS", "SOURCE_ON_FREE_PLAN", "ALLOCATION_NOT_ALLOWED", "TARGET_PLAN_CHANGE_FAILED"];
+type AllocationErrorCode = (typeof ALLOCATION_ERROR_CODES)[number];
+/** The billing allocation error in a failure: its code, details and server message. */
+declare function findAllocationError(failure: unknown): {
+    code: AllocationErrorCode;
+    details: Record<string, unknown>;
+    message: string | null;
+} | null;
+/**
+ * A plain sentence for a billing allocation refusal, or `null` when the
+ * failure is not one (the caller then falls back to its generic message).
+ */
+declare function allocationErrorMessage(failure: unknown): string | null;
+
+/**
+ * Billing sub-view: credits this workspace shares with, or receives from,
+ * other workspaces of its organization. Changes are for organization admins
+ * (`canManage` from the server); everyone else who reaches Billing reads.
+ */
+declare function CreditAllocationsView(): react.JSX.Element;
+
+type CreditAllocationModalProps = {
+    kind: "create";
+    /** Workspaces credits can go to. */
+    targets: CreditAllocationTarget[];
+    /** This workspace's available credits, when known: the first share comes out of it. */
+    balance: number | null;
+    onSave: (input: CreateCreditAllocationInput) => Promise<CreditAllocation>;
+    onClose: () => void;
+    /** After a save (or a failure that still left an allocation); the parent refetches. */
+    onSaved: () => void;
+} | {
+    kind: "edit";
+    allocation: CreditAllocation;
+    targetName: string;
+    onSave: (patch: UpdateCreditAllocationInput) => Promise<CreditAllocation>;
+    onClose: () => void;
+    onSaved: () => void;
+};
+/** Create an allocation, or change an active one's split and repeat. */
+declare function CreditAllocationModal(props: CreditAllocationModalProps): react.JSX.Element;
+
+interface CancelCreditAllocationModalProps {
+    allocation: CreditAllocation;
+    targetName: string;
+    onCancel: (reason: string) => Promise<CancelCreditAllocationResult>;
+    onClose: () => void;
+    /**
+     * After the allocation was canceled; the parent refetches. `planNotRestored`
+     * is true when the target was left on the Custom plan and someone has to fix it.
+     */
+    onCanceled: (result: {
+        planNotRestored: boolean;
+    }) => void;
+}
+/**
+ * Confirm a cancel with a reason. Billing cancels even when moving the target
+ * back to free fails; that outcome stays on screen (not a toast that can be
+ * missed) until the admin acknowledges it.
+ */
+declare function CancelCreditAllocationModal({ allocation, targetName, onCancel, onClose, onCanceled, }: CancelCreditAllocationModalProps): react.JSX.Element;
+
 declare function SettingsAdaptersProvider({ adapters, children, }: {
     adapters: SettingsAdapters;
     children: ReactNode;
@@ -1904,4 +2168,4 @@ declare function SettingsAdaptersProvider({ adapters, children, }: {
  */
 declare function useSettingsAdapters(): SettingsAdapters;
 
-export { APP_KEYS, type ApiToken, type AppKey, 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 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, PerUserLimitsView, type Price, type PriceMetadata, type ProductsResponse, ProfileAvatar, ProfileTab, ReferralTab, 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 SettingsOrganizationListItem, type SettingsOrganizationType, type SettingsScope, type SettingsTab, type SettingsToastAdapter, SettingsTooltip, type SettingsTooltipPlacement, type SettingsTooltipProps, type SettingsWorkspaceAdapter, type SettingsWorkspaceCurrent, type SettingsWorkspaceListItem, 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 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, cleanCreditLimitInput, countLabel, creditCycleUnit, describeDefaultLimit, describeMemberLimit, formatCreditLimit, formatCredits, groupWorkspaceList, isLimitBelowUsage, joinMembersWithLimits, lastUsedLabel, limitBelowUsageUsed, limitSourceLabel, loadWorkspaceOrganization, memberRoleUpdate, minimumCreditLimit, resolveSettingsTabFromPath, roundCredits, useSettingsAdapters, useWorkspaceOrganization, userLanguageLabel, validateCreditLimitInput, validateDefaultCreditLimitInput };
+export { ALLOCATION_ERROR_CODES, ALLOCATION_NOTE_MAX_LENGTH, APP_KEYS, type AllocationErrorCode, type AllocationValueValidation, type ApiToken, type AppKey, type AvailableCreditsResponse, BillingContent, type BillingEventPayload, type BillingProduct, type BillingSubscription, BuyCreditsModal, type BuyCreditsPayload, type BuyCreditsResponse, CANCEL_REASON_MAX_LENGTH, CancelCreditAllocationModal, type CancelCreditAllocationModalProps, type CancelCreditAllocationResult, ConfirmDeleteModal, ConfirmLeaveModal, type ConnectedApp, ConnectedAppsContent, type CreateCreditAllocationInput, type CreatedToken, type CreditAllocation, CreditAllocationModal, type CreditAllocationModalProps, type CreditAllocationMode, type CreditAllocationStatus, type CreditAllocationTarget, type CreditAllocationsResponse, CreditAllocationsView, type CreditCycleUnit, type CreditLimitValidation, type CreditTransfer, type CreditTransfersPage, 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, PerUserLimitsView, type Price, type PriceMetadata, type ProductsResponse, ProfileAvatar, ProfileTab, ReferralTab, 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 SettingsOrganizationListItem, type SettingsOrganizationType, type SettingsScope, type SettingsTab, type SettingsToastAdapter, SettingsTooltip, type SettingsTooltipPlacement, type SettingsTooltipProps, type SettingsWorkspaceAdapter, type SettingsWorkspaceCurrent, type SettingsWorkspaceListItem, 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 UpdateCreditAllocationInput, 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, allocationErrorMessage, allocationWorkspaceName, belowUsageReason, canShowCreditAllocations, cancelOutcomeSummary, cancelOutcomeWarning, cleanAllocationValueInput, cleanCreditLimitInput, countLabel, creditCycleUnit, describeAllocation, describeDefaultLimit, describeMemberLimit, findAllocationError, findBillingError, formatAllocationRepeat, formatAllocationSplit, formatCreditLimit, formatCredits, groupWorkspaceList, initialTransferSummary, initialTransferWarning, isLimitBelowUsage, joinMembersWithLimits, lastUsedLabel, limitBelowUsageUsed, limitSourceLabel, loadWorkspaceOrganization, memberRoleUpdate, minimumCreditLimit, resolveSettingsTabFromPath, roundCredits, useSettingsAdapters, useWorkspaceOrganization, userLanguageLabel, validateAllocationText, validateAllocationValue, validateCreditLimitInput, validateDefaultCreditLimitInput };