Line data Source code
1 : /**
2 : * Why a capability resolved false, decoded from the capabilities read.
3 : *
4 : * The server's contract runs one way only, and every reader here depends on
5 : * it: a reason is present only alongside `capabilities.<key> === false`, so
6 : * presence implies refusal — but absence implies nothing at all. A capability
7 : * with no reason may be granted, may be refused by a billing-api that predates
8 : * the field, or may be refused for a reason the server declined to forward.
9 : * `capabilities` stays the only authority for what a client may offer; these
10 : * keys only ever choose the wording for a refusal already decided there.
11 : */
12 : import { z } from 'zod'
13 :
14 : /**
15 : * The policy branches the server names, plus the bucket this module adds for
16 : * a value it does not recognize. `not_a_member` is unreachable through the
17 : * ingest endpoint — a non-member is answered 403 before capabilities resolve —
18 : * and is carried anyway because the billing-api endpoint can still emit it.
19 : */
20 : export type CapabilityDenialReason =
21 : | 'not_a_member'
22 : | 'not_workspace_owner'
23 : | 'tier_not_self_serve'
24 : /** A subscription row reserved before payment that never began. */
25 : | 'subscription_not_started'
26 : /** The subscription already has a successor scheduled at a billing boundary. */
27 : | 'subscription_change_in_progress'
28 : /** The server has no guidance for the row — distinct from a deliberate refusal. */
29 : | 'subscription_status_unrecognized'
30 : | 'not_original_owner'
31 : | 'creator_only_provisioning'
32 : | 'payment_past_due'
33 : | 'topup_purchases_paused'
34 : | 'free_plan'
35 : | 'no_subscription'
36 : | 'subscription_ended'
37 : | 'billing_operation_in_progress'
38 : | 'billing_operation_parked'
39 : | 'cancellation_scheduled'
40 : | 'cancellation_not_scheduled'
41 : | 'workspace_sso_attached'
42 : | 'personal_workspace'
43 : | 'plan_not_ended'
44 : | 'membership_managed_by_directory'
45 : | 'personal_workspace_creator'
46 : | 'workspace_creator'
47 : | 'workspace_owner'
48 : | 'only_owner'
49 : | 'billing_state_unknown'
50 : | 'free_tier_exhausted'
51 : | 'invite_capacity_reached'
52 : | 'manual_block'
53 : | 'no_funds'
54 : | 'no_revertible_scheduled_change'
55 : | 'no_upgrade_available'
56 : | 'partner_governance_not_entitled'
57 : | 'plan_ending'
58 : | 'plan_not_enterprise'
59 : | 'project_cap_exceeded'
60 : | 'rollout_disabled'
61 : | 'sales_managed'
62 : | 'sales_managed_plan'
63 : | 'subscription_inactive'
64 : | 'usage_attribution_unavailable'
65 : | 'user_cap_exceeded'
66 : | 'workspace_cap_exceeded'
67 : /**
68 : * A reason outside the set above. Kept as a reason rather than dropped so a
69 : * refusal the server explained still reads as explained; the copy it maps to
70 : * is the generic one.
71 : */
72 : | 'unspecified'
73 :
74 2356 : const KNOWN_REASONS: Readonly<
75 : Record<Exclude<CapabilityDenialReason, 'unspecified'>, true>
76 : > = {
77 : not_a_member: true,
78 : not_workspace_owner: true,
79 : tier_not_self_serve: true,
80 : subscription_not_started: true,
81 : subscription_change_in_progress: true,
82 : subscription_status_unrecognized: true,
83 : not_original_owner: true,
84 : creator_only_provisioning: true,
85 : payment_past_due: true,
86 : topup_purchases_paused: true,
87 : free_plan: true,
88 : no_subscription: true,
89 : subscription_ended: true,
90 : billing_operation_in_progress: true,
91 : billing_operation_parked: true,
92 : cancellation_scheduled: true,
93 : cancellation_not_scheduled: true,
94 : workspace_sso_attached: true,
95 : personal_workspace: true,
96 : plan_not_ended: true,
97 : membership_managed_by_directory: true,
98 : personal_workspace_creator: true,
99 : workspace_creator: true,
100 : workspace_owner: true,
101 : only_owner: true,
102 : billing_state_unknown: true,
103 : free_tier_exhausted: true,
104 : invite_capacity_reached: true,
105 : manual_block: true,
106 : no_funds: true,
107 : no_revertible_scheduled_change: true,
108 : no_upgrade_available: true,
109 : partner_governance_not_entitled: true,
110 : plan_ending: true,
111 : plan_not_enterprise: true,
112 : project_cap_exceeded: true,
113 : rollout_disabled: true,
114 : sales_managed: true,
115 : sales_managed_plan: true,
116 : subscription_inactive: true,
117 : usage_attribution_unavailable: true,
118 : user_cap_exceeded: true,
119 : workspace_cap_exceeded: true
120 : }
121 :
122 : /**
123 : * The record is open because the server adds keys as policy grows, and a
124 : * client that rejected an unknown key would fail the whole read over a field
125 : * it does not use.
126 : */
127 : export type CapabilityDenials = Readonly<
128 : Partial<Record<string, CapabilityDenialReason>>
129 : >
130 :
131 : /**
132 : * Deliberately lenient: values are read as plain strings and narrowed here,
133 : * never as a generated enum. A strict enum parse would make the entire
134 : * capabilities read malformed the first time the server names a policy branch
135 : * this client predates — turning a copy detail into a total loss of the
136 : * capability set, which is the one part of the response that gates UI.
137 : *
138 : * This mirrors what the ingest service already does on its own side, where an
139 : * unrecognized reason is dropped rather than forwarded.
140 : */
141 2356 : const DeniedReasonsSchema = z.record(z.string(), z.string()).optional()
142 :
143 0 : export function decodeCapabilityDenials(raw: unknown): CapabilityDenials {
144 0 : const parsed = DeniedReasonsSchema.safeParse(raw)
145 0 : if (!parsed.success || parsed.data === undefined) return {}
146 :
147 0 : const denials: Record<string, CapabilityDenialReason> = {}
148 0 : for (const [capability, reason] of Object.entries(parsed.data)) {
149 0 : denials[capability] = Object.hasOwn(KNOWN_REASONS, reason)
150 : ? (reason as CapabilityDenialReason)
151 : : 'unspecified'
152 : }
153 0 : return denials
154 : }
|