| 1 | import type { ComputeKind, Reservation } from "./compute"; |
| 2 | import type { PauseLevel } from "./platform"; |
| 3 | import type { User, Viewer } from "./identity"; |
| 4 | import type { RepoPath } from "./repos"; |
| 5 | import type { Result } from "./result"; |
| 6 | |
| 7 | /** Millionths of a US dollar in one dollar: the unit money is held in. */ |
| 8 | export const MICROS_PER_DOLLAR = 1_000_000; |
| 9 | |
| 10 | /** Whether workspaces are charged for agents at all, and with real money. */ |
| 11 | export type BillingStatus = { |
| 12 | /** |
| 13 | * False when no card processor is configured: nothing is charged, and who |
| 14 | * may run agents is decided some other way. |
| 15 | */ |
| 16 | enabled: boolean; |
| 17 | /** False while the card processor is in its test mode, where cards are not real. */ |
| 18 | live: boolean; |
| 19 | /** |
| 20 | * True while g1t is being built out: runs are recorded with what they |
| 21 | * cost, but nothing is charged and no credit is needed. Not forever. |
| 22 | */ |
| 23 | free?: boolean; |
| 24 | }; |
| 25 | |
| 26 | /** A workspace's standing. */ |
| 27 | export type BillingAccount = { |
| 28 | workspace: string; |
| 29 | /** |
| 30 | * Credit left, in millionths of a dollar. Can dip below zero by the cost |
| 31 | * of the runs that were under way when it ran out. |
| 32 | */ |
| 33 | balanceMicros: number; |
| 34 | status: BillingStatus; |
| 35 | /** What is added to a run's cost, in percent. */ |
| 36 | marginPercent: number; |
| 37 | /** The card charged near the limit and when a month closes, if one is saved. */ |
| 38 | card?: { brand: string; last4: string; expMonth: number; expYear: number } | null; |
| 39 | }; |
| 40 | |
| 41 | /** One line of a workspace's statement. */ |
| 42 | export type LedgerEntry = { |
| 43 | id: string; |
| 44 | /** Credit bought with a card, or an agent's run. */ |
| 45 | kind: "top_up" | "usage"; |
| 46 | /** Positive for credit added, negative for usage. */ |
| 47 | amountMicros: number; |
| 48 | description: string; |
| 49 | /** For usage: the repository and pull request the agent worked on. */ |
| 50 | repo: string | null; |
| 51 | number: number | null; |
| 52 | /** For usage: `implement`, `review` or `update`. */ |
| 53 | task: string | null; |
| 54 | /** For usage: the model, by its public name. */ |
| 55 | model: string | null; |
| 56 | /** For usage: who paid the model provider. */ |
| 57 | billedTo: "g1t" | "workspace"; |
| 58 | /** For a top-up: the username of whoever paid. */ |
| 59 | createdBy: string | null; |
| 60 | /** RFC 3339. */ |
| 61 | createdAt: string; |
| 62 | /** The workspace the line belongs to, which tells an enterprise's lines apart. */ |
| 63 | workspace?: string | null; |
| 64 | /** For usage: what the plan's included usage paid of it. `amountMicros` is what is left to pay. */ |
| 65 | creditMicros?: number; |
| 66 | /** For usage: what the workspace's trial credit paid of it. */ |
| 67 | trialMicros?: number; |
| 68 | /** For usage: what g1t's open-source pool paid of it. */ |
| 69 | ossMicros?: number; |
| 70 | /** For usage: what g1t covered itself, such as a trial's last run past its credit. */ |
| 71 | givenMicros?: number; |
| 72 | /** For usage: what a complimentary allowance from g1t paid of it. */ |
| 73 | giftMicros?: number; |
| 74 | /** For usage: what the account's discount took off its price. */ |
| 75 | discountMicros?: number; |
| 76 | /** For a credit from g1t, and for what of one expired or was revoked: its kind. */ |
| 77 | creditKind?: CreditKind; |
| 78 | }; |
| 79 | |
| 80 | /** |
| 81 | * Why g1t gave a workspace credit. Promotional (a welcome, a referral) and |
| 82 | * goodwill (an apology) are given away when spent; a refund gives back |
| 83 | * money already paid, and never expires. |
| 84 | */ |
| 85 | export type CreditKind = "promotional" | "goodwill" | "refund" | "purchased"; |
| 86 | |
| 87 | /** One credit g1t gave, with what of it was used: spent before anything paid in advance, the soonest-expiring first. */ |
| 88 | export type CreditGrant = { |
| 89 | /** `crd_…`, the grant's ledger reference. */ |
| 90 | id: string; |
| 91 | workspace: string; |
| 92 | kind: CreditKind; |
| 93 | amountMicros: number; |
| 94 | usedMicros: number; |
| 95 | /** What can still be spent: nothing once it expired or was revoked. */ |
| 96 | leftMicros: number; |
| 97 | note: string; |
| 98 | /** A refund: what it refunds, and the day of it. */ |
| 99 | refundFor?: string | null; |
| 100 | refundDay?: string | null; |
| 101 | /** RFC 3339; null never expires. */ |
| 102 | expiresAt: string | null; |
| 103 | createdBy: string; |
| 104 | createdAt: string; |
| 105 | state: "open" | "used" | "expired" | "revoked"; |
| 106 | closedAt?: string | null; |
| 107 | closedNote?: string | null; |
| 108 | closedBy?: string | null; |
| 109 | /** What expiring or revoking took off the balance. */ |
| 110 | closedMicros?: number; |
| 111 | /** What it pays for: all usage, or models only (spent first). */ |
| 112 | scope?: "all" | "models"; |
| 113 | /** Where it came from. */ |
| 114 | source?: "staff" | "purchase" | "promo_code" | "upgrade"; |
| 115 | }; |
| 116 | |
| 117 | /** A workspace's credits from g1t, newest first. */ |
| 118 | export type Credits = { grants: CreditGrant[]; leftMicros: number }; |
| 119 | |
| 120 | /** One month's credits of one kind: given, spent that month, and taken back unused. */ |
| 121 | export type CreditMonth = { |
| 122 | month: string; |
| 123 | kind: CreditKind; |
| 124 | givenMicros: number; |
| 125 | grants: number; |
| 126 | usedMicros: number; |
| 127 | expiredMicros: number; |
| 128 | revokedMicros: number; |
| 129 | }; |
| 130 | |
| 131 | /** Every credit g1t gave (at most 200, filtered), the last 12 months by kind, and who gave them. */ |
| 132 | export type AdminCredits = { grants: CreditGrant[]; months: CreditMonth[]; staff: string[] }; |
| 133 | |
| 134 | /** What a credit from sudo is, past its amount and note. */ |
| 135 | export type CreditOptions = { |
| 136 | kind: CreditKind; |
| 137 | /** RFC 3339; never for a refund. */ |
| 138 | expiresAt?: string | null; |
| 139 | /** A refund: what it is for, and the day refunded (`YYYY-MM-DD`). */ |
| 140 | refundFor?: string | null; |
| 141 | refundDay?: string | null; |
| 142 | }; |
| 143 | |
| 144 | /** |
| 145 | * How an account is charged. Standard unless g1t set otherwise in sudo: |
| 146 | * custom terms are a discount (0 to 100%), a ceiling, or both. A 100% |
| 147 | * discount charges nothing and shows the usage at its price. `comped` is |
| 148 | * from before discounts and reads as 100%; billing no longer writes it. |
| 149 | */ |
| 150 | export type Terms = { |
| 151 | kind: "standard" | "comped" | "custom"; |
| 152 | discountPercent: number; |
| 153 | ceilingMicros: number | null; |
| 154 | note: string; |
| 155 | until: string | null; |
| 156 | setBy: string | null; |
| 157 | setAt: string | null; |
| 158 | }; |
| 159 | |
| 160 | /** |
| 161 | * Who pays: a workspace's own account, or an enterprise's, which pays for |
| 162 | * several workspaces with one bill and one limit. |
| 163 | */ |
| 164 | export type PayingAccount = { |
| 165 | id: string; |
| 166 | kind: "workspace" | "enterprise"; |
| 167 | name: string; |
| 168 | terms: Terms; |
| 169 | workspaces: string[]; |
| 170 | /** Where an enterprise's invoices go. */ |
| 171 | billingEmail?: string | null; |
| 172 | /** An enterprise's invoices, newest first. */ |
| 173 | invoices?: EnterpriseInvoice[]; |
| 174 | createdAt: string; |
| 175 | /** What g1t staff set for the account beyond its terms. */ |
| 176 | allowances?: Allowances; |
| 177 | }; |
| 178 | |
| 179 | /** Set per account by g1t staff in sudo, on top of its terms. */ |
| 180 | export type Allowances = { |
| 181 | /** The g1t plan without its monthly price; usage is charged as usual. Comped accounts have it anyway. */ |
| 182 | plan: boolean; |
| 183 | /** Each public repository's monthly cap on g1t's open-source pool; null for the default. */ |
| 184 | ossRepoMicros: number | null; |
| 185 | /** Each workspace's trial credit, outside the monthly pool; null for the default. */ |
| 186 | trialMicros: number | null; |
| 187 | /** Agents at once, in place of the plan's (2 in the first month or on the trial, then 10); null for the default. */ |
| 188 | maxConcurrentAgents?: number | null; |
| 189 | /** Days of audit log its workspaces keep, in place of the plan's (7 free, 90 on the plan), longer or shorter; null for the plan's. */ |
| 190 | auditRetentionDays?: number | null; |
| 191 | /** A hold on new compute, with why; null for none. */ |
| 192 | hold?: string | null; |
| 193 | }; |
| 194 | |
| 195 | // --- Entitlements, and compute started under a reservation ------------------ |
| 196 | // |
| 197 | // Every service that starts compute asks billing first: |
| 198 | // 1. `entitlements(workspace)`: what it may do at all, its caps, and whether compute is paused. |
| 199 | // 2. `reserve(...)`: holds the estimate against what may pay for it, so starts at the same moment |
| 200 | // cannot overshoot together. Answers who pays first, or refuses with a stable code |
| 201 | // (`not_paid`, `trial_used`, `limit`, `paused`, `oss_pool_empty`) and a message for the owner. |
| 202 | // 3. `settle(reservationId, actualMicros)`: releases the hold. The charge goes on the ledger the usual way. |
| 203 | // A reservation never settled lapses after `RESERVATION_HOURS`. |
| 204 | |
| 205 | /** A reservation that is never settled stops holding after this long. */ |
| 206 | export const RESERVATION_HOURS = 3; |
| 207 | /** What a ceiling reads as when there is none (g1t's own workspaces). */ |
| 208 | export const UNLIMITED_MICROS = 1_000_000_000_000_000; |
| 209 | |
| 210 | /** What a workspace pays g1t on, as far as compute is concerned. Mirrors `PlanKind`. */ |
| 211 | export type PlanKind = "free" | "paid" | "internal" | "enterprise" | "complimentary"; |
| 212 | |
| 213 | // `ComputeKind` (what compute is for), `PaidBy` (who pays first: credit, trial, oss, on_demand) and |
| 214 | // `Reservation` are in `./compute`, with the gate that calls `reserve` and `settle`. |
| 215 | |
| 216 | /** One level reached: 50, 75, 90 or 100 percent. */ |
| 217 | export type UsageAlert = { |
| 218 | /** `included` (the plan's included usage), `spend_limit` or `ceiling`. */ |
| 219 | meter: "included" | "spend_limit" | "ceiling" | string; |
| 220 | level: number; |
| 221 | usedMicros: number; |
| 222 | limitMicros: number; |
| 223 | message: string; |
| 224 | }; |
| 225 | |
| 226 | /** An hour's spend well above the workspace's usual: new compute waits for an owner. */ |
| 227 | export type Spike = { |
| 228 | id: string; |
| 229 | /** `open` (waiting), `continued` (keep going) or `stopped`. */ |
| 230 | status: "open" | "continued" | "stopped" | string; |
| 231 | hourMicros: number; |
| 232 | averageMicros: number; |
| 233 | detectedAt: string; |
| 234 | decidedBy?: string | null; |
| 235 | decidedAt?: string | null; |
| 236 | /** While continued: until when, unless spend doubles again first. */ |
| 237 | until?: string | null; |
| 238 | }; |
| 239 | |
| 240 | /** What a workspace may do now. Mirrors `Entitlements` in `crates/contracts/src/billing.rs`. */ |
| 241 | export type Entitlements = { |
| 242 | workspace: string; |
| 243 | plan: PlanKind; |
| 244 | /** May start sandboxes, models, deployments and semantic search at all: paid, internal, enterprise, or free with trial credit left. */ |
| 245 | compute: boolean; |
| 246 | /** The one-time trial credit left; 0 if none or used. */ |
| 247 | trialMicrosLeft: number; |
| 248 | /** A card check has been done; the trial and the open-source pool need it. */ |
| 249 | trialVerified: boolean; |
| 250 | /** A paid workspace still in its first billing cycle. */ |
| 251 | firstMonth: boolean; |
| 252 | /** 2 in the first month or on the trial, 10 after; staff can override it. */ |
| 253 | maxConcurrentAgents: number; |
| 254 | /** 60 in the first month or on the trial; otherwise the guardrails' own caps. */ |
| 255 | maxRunMinutes: number; |
| 256 | /** g1t's ceiling on usage not yet paid for; `UNLIMITED_MICROS` for g1t's own; 0 for free. */ |
| 257 | ceilingMicros: number; |
| 258 | /** Usage not yet paid for this month, prepayment taken off. */ |
| 259 | exposureMicros: number; |
| 260 | /** Why new compute is paused, for the owner; null when it is not. */ |
| 261 | paused: string | null; |
| 262 | /** g1t staff put a hold on the account: nothing new is set up for it, such as a self-hosted runner. */ |
| 263 | held?: boolean; |
| 264 | /** What open reservations hold now. */ |
| 265 | heldMicros?: number; |
| 266 | /** Paid in advance and not used yet. */ |
| 267 | prepaidMicros?: number; |
| 268 | /** The plan's included usage each month, and what of it is used. */ |
| 269 | includedMicros?: number; |
| 270 | includedUsedMicros?: number; |
| 271 | /** How far back the audit log can be read and exported, and what is kept: the plan's days, or what g1t staff set for the account. */ |
| 272 | auditRetentionDays: number; |
| 273 | /** Whether `auditRetentionDays` is what staff set for the account rather than the plan's. */ |
| 274 | auditRetentionCustom?: boolean; |
| 275 | /** Private repository storage free for every workspace: past it, the plan pays and a free workspace's pushes stop. */ |
| 276 | freePrivateStorageBytes: number; |
| 277 | /** The last daily measure of the workspace's private repositories (a lower bound). */ |
| 278 | privateStorageBytes: number; |
| 279 | /** On a paid plan: package storage past the free amounts is charged, never refused. */ |
| 280 | hasPlan?: boolean; |
| 281 | /** Package storage free for every workspace (public, and private): past it a free workspace's pushes are refused. */ |
| 282 | packagePublicFreeBytes?: number; |
| 283 | packagePrivateFreeBytes?: number; |
| 284 | /** What g1t's open-source pool paid for the workspace this month. */ |
| 285 | ossPaidMicros: number; |
| 286 | /** Deploy build time this month, every second of it metered. */ |
| 287 | buildSecondsUsed?: number; |
| 288 | /** Git operations this month, and how many are free for every workspace. */ |
| 289 | gitOperations?: number; |
| 290 | gitOperationsIncluded?: number; |
| 291 | /** The smallest amount a card is charged when a month closes. */ |
| 292 | minChargeMicros: number; |
| 293 | /** A spend spike waiting for an owner, or decided. */ |
| 294 | spike?: Spike | null; |
| 295 | /** Where usage stands against what is included and the limits, from 50%. */ |
| 296 | alerts?: UsageAlert[]; |
| 297 | /** A complimentary enrollment's allowance this month. */ |
| 298 | complimentary?: ComplimentaryMonth | null; |
| 299 | }; |
| 300 | |
| 301 | /** A complimentary allowance this calendar month (UTC). Usage counts at its ordinary price. Mirrors `ComplimentaryMonth`. */ |
| 302 | export type ComplimentaryMonth = { |
| 303 | /** `YYYY-MM`. */ |
| 304 | month: string; |
| 305 | allowanceMicros: number; |
| 306 | unlimited?: boolean; |
| 307 | /** Usage this month the allowance paid for. */ |
| 308 | usedMicros: number; |
| 309 | /** Metered this month and not on the ledger yet (storage, git operations), which the allowance will pay for. */ |
| 310 | pendingMicros?: number; |
| 311 | /** What running work holds against it. */ |
| 312 | heldMicros?: number; |
| 313 | /** What is left after all three: at 0, new work that costs money stops. */ |
| 314 | remainingMicros: number; |
| 315 | /** What g1t covered past the allowance this month: never charged. */ |
| 316 | overrunMicros?: number; |
| 317 | /** RFC 3339: when next month's allowance starts. */ |
| 318 | resetsAt: string; |
| 319 | /** The recurring monthly fee, in cents; 0: waived. */ |
| 320 | feeCents?: number; |
| 321 | /** Past the allowance, usage is charged to the workspace's own card under its limits; otherwise new paid work stops. */ |
| 322 | chargePastAllowance?: boolean; |
| 323 | /** A card is on file to charge past the allowance. */ |
| 324 | hasCard?: boolean; |
| 325 | }; |
| 326 | |
| 327 | /** A complimentary enrollment, as sudo shows it. Mirrors `ComplimentaryStanding`. */ |
| 328 | export type ComplimentaryStanding = { |
| 329 | workspace: string; |
| 330 | grantId: string; |
| 331 | /** `pending` (Stripe not confirmed yet), `active` or `ended`. */ |
| 332 | status: "pending" | "active" | "ended"; |
| 333 | allowanceMicros: number; |
| 334 | unlimited?: boolean; |
| 335 | feeCents?: number; |
| 336 | chargePastAllowance?: boolean; |
| 337 | live?: boolean; |
| 338 | customerId?: string | null; |
| 339 | subscriptionId?: string | null; |
| 340 | stripeStatus?: string | null; |
| 341 | /** A Stripe step still owed, tried again every fifteen minutes. */ |
| 342 | pendingOp?: "create" | "terms" | "cancel" | "convert" | null; |
| 343 | lastError?: string | null; |
| 344 | note: string; |
| 345 | createdBy: string; |
| 346 | createdAt: string; |
| 347 | updatedBy: string; |
| 348 | updatedAt: string; |
| 349 | endedAt?: string | null; |
| 350 | endedReason?: "revoked" | "converted" | null; |
| 351 | month?: ComplimentaryMonth | null; |
| 352 | periods?: ComplimentaryPeriod[]; |
| 353 | /** Money actually paid to g1t, all time: plan and fee invoices, prepayments, bank transfers. */ |
| 354 | moneyReceivedMicros?: number; |
| 355 | /** Promotional and goodwill credit from g1t, all time: never money. */ |
| 356 | promotionalCreditMicros?: number; |
| 357 | /** Usage complimentary allowances paid for, all time: never money. */ |
| 358 | giftedMicros?: number; |
| 359 | }; |
| 360 | |
| 361 | export type ComplimentaryPeriod = { |
| 362 | id: string; |
| 363 | startsAt: string; |
| 364 | endsAt?: string | null; |
| 365 | allowanceMicros: number; |
| 366 | unlimited?: boolean; |
| 367 | feeCents?: number; |
| 368 | chargePastAllowance?: boolean; |
| 369 | note: string; |
| 370 | createdBy: string; |
| 371 | }; |
| 372 | |
| 373 | /** Where an owner's conversion to the plan stands. */ |
| 374 | export type Conversion = { |
| 375 | status: "converted" | "needs_card" | "needs_action" | "declined"; |
| 376 | url?: string | null; |
| 377 | message: string; |
| 378 | }; |
| 379 | |
| 380 | /** A hold on a start's estimated cost, as billing answers it (`Reservation` in `./compute`, and more). */ |
| 381 | export type ReservationHeld = Reservation & { |
| 382 | /** What is held, at cost; may be less than the estimate for a free workspace's last bit of trial. */ |
| 383 | heldMicros?: number; |
| 384 | /** When the hold lapses if never settled. */ |
| 385 | expiresAt?: string; |
| 386 | }; |
| 387 | |
| 388 | /** A request to g1t: a higher limit, or help with usage past what was meant. */ |
| 389 | export type LimitRequest = { |
| 390 | id: string; |
| 391 | workspace: string; |
| 392 | kind: "limit" | "overage" | string; |
| 393 | amountMicros: number; |
| 394 | reason: string; |
| 395 | expectedMonthlyMicros: number; |
| 396 | status: "open" | "approved" | "declined" | string; |
| 397 | decidedMicros?: number | null; |
| 398 | decidedBy?: string | null; |
| 399 | /** The answer, as the owner sees it. */ |
| 400 | answer?: string | null; |
| 401 | createdBy: string; |
| 402 | createdAt: string; |
| 403 | decidedAt?: string | null; |
| 404 | }; |
| 405 | |
| 406 | /** What staff see beside a request. */ |
| 407 | export type WorkspaceHistory = { |
| 408 | plan: PlanKind | null; |
| 409 | months: MonthFigures[]; |
| 410 | paidClearedMicros: number; |
| 411 | payments: number; |
| 412 | disputes: number; |
| 413 | declines: number; |
| 414 | firstSeen: string | null; |
| 415 | ceilingMicros: number | null; |
| 416 | maxCeilingMicros: number | null; |
| 417 | spendLimitMicros: number | null; |
| 418 | lastHourMicros: number; |
| 419 | averageHourMicros: number; |
| 420 | lastDayMicros: number; |
| 421 | }; |
| 422 | |
| 423 | export type LimitRequestReview = { request: LimitRequest; history: WorkspaceHistory }; |
| 424 | |
| 425 | /** What a one-time goodwill credit comes to: the margin on the overage, always, plus its cost up to the cap. */ |
| 426 | export type Goodwill = { |
| 427 | overageMicros: number; |
| 428 | marginMicros: number; |
| 429 | costMicros: number; |
| 430 | creditMicros: number; |
| 431 | absorbedMicros: number; |
| 432 | }; |
| 433 | |
| 434 | /** A workspace whose month went well past its usual, or hit a spike. */ |
| 435 | export type Overage = { |
| 436 | workspace: string; |
| 437 | plan: PlanKind; |
| 438 | typicalMonthMicros: number; |
| 439 | thisMonthMicros: number; |
| 440 | costMicros: number; |
| 441 | marginMicros: number; |
| 442 | spike: Spike | null; |
| 443 | topEntries: LedgerEntry[]; |
| 444 | goodwill: Goodwill; |
| 445 | goodwillAvailable: boolean; |
| 446 | lastGoodwillAt: string | null; |
| 447 | request: LimitRequest | null; |
| 448 | }; |
| 449 | |
| 450 | /** One workspace's recent pace. */ |
| 451 | export type Velocity = { |
| 452 | workspace: string; |
| 453 | plan: PlanKind; |
| 454 | lastHourMicros: number; |
| 455 | averageHourMicros: number; |
| 456 | lastDayMicros: number; |
| 457 | thisMonthMicros: number; |
| 458 | ratio: number; |
| 459 | spike: Spike | null; |
| 460 | firstSeen: string | null; |
| 461 | }; |
| 462 | |
| 463 | /** g1t's capped budgets for free usage this month. */ |
| 464 | export type Pools = { |
| 465 | month: string; |
| 466 | trialGrantedMicros: number; |
| 467 | trialPoolMicros: number; |
| 468 | trialGrants: number; |
| 469 | ossUsedMicros: number; |
| 470 | ossPoolMicros: number; |
| 471 | ossRepoMicros: number; |
| 472 | }; |
| 473 | |
| 474 | export type AccountSummary = { |
| 475 | account: PayingAccount; |
| 476 | limit: Limit; |
| 477 | chargedMicros: number; |
| 478 | costMicros: number; |
| 479 | paidMicros: number; |
| 480 | /** The same figures for each of the account's workspaces that has any. */ |
| 481 | byWorkspace: WorkspaceFigures[]; |
| 482 | /** The last six months, oldest first. */ |
| 483 | months?: MonthFigures[]; |
| 484 | }; |
| 485 | |
| 486 | /** One workspace's share of an `AccountSummary`. */ |
| 487 | export type WorkspaceFigures = { workspace: string; chargedMicros: number; costMicros: number; paidMicros: number }; |
| 488 | |
| 489 | export type StripeStatus = { |
| 490 | /** `test` or `live`, from the key; `off` without one. */ |
| 491 | mode: "test" | "live" | "off" | string; |
| 492 | /** Whether `STRIPE_WEBHOOK_SECRET` is set, so events can be checked. */ |
| 493 | secretSet: boolean; |
| 494 | /** The destination at billing's address in Stripe, as Stripe has it. */ |
| 495 | webhook: { url: string; endpointId: string; status: "enabled" | "disabled" | string; events: string[]; createdAt: string } | null; |
| 496 | /** Events billing handles that the destination does not send. */ |
| 497 | missingEvents: string[]; |
| 498 | recentEvents: { id: string; kind: string; outcome: string; receivedAt: string }[]; |
| 499 | error: string | null; |
| 500 | /** Stripe Tax for the key's mode: `active`, or `pending` with the settings it still needs. Null when it could not be read. */ |
| 501 | tax?: { status: "active" | "pending" | string; missingFields: string[] } | null; |
| 502 | /** The customer portal configuration billing makes (`metadata[g1t]=billing`). Null until the first portal session makes it. */ |
| 503 | portal?: { configurationId: string; active: boolean } | null; |
| 504 | }; |
| 505 | |
| 506 | /** An enterprise's invoice: one line per workspace, paid on Stripe's page. */ |
| 507 | export type EnterpriseInvoice = { |
| 508 | invoiceId: string; |
| 509 | hostedUrl: string | null; |
| 510 | amountMicros: number; |
| 511 | status: "open" | "paid" | "overdue" | "void" | string; |
| 512 | period: string; |
| 513 | lines: { workspace: string; amountMicros: number }[]; |
| 514 | createdAt: string; |
| 515 | }; |
| 516 | |
| 517 | /** A workspace's invoice: monthly, or when charged near its limit. Itemised, in Stripe's billing page. */ |
| 518 | export type WorkspaceInvoice = { |
| 519 | invoiceId: string; |
| 520 | workspace: string; |
| 521 | reason: "month" | "threshold" | string; |
| 522 | period: string; |
| 523 | amountMicros: number; |
| 524 | status: "paid" | "open" | "failed" | "void" | string; |
| 525 | hostedUrl: string | null; |
| 526 | pdfUrl: string | null; |
| 527 | lines: { description: string; amountMicros: number }[]; |
| 528 | createdAt: string; |
| 529 | /** The card processing fee on top of `amountMicros` (only on invoices from before g1t's prices included it), and the tax Stripe added once known. */ |
| 530 | feeMicros?: number; |
| 531 | taxMicros?: number; |
| 532 | }; |
| 533 | |
| 534 | /** A month of the ledger, grouped by day or project, a line per kind of charge. */ |
| 535 | export type Statement = { |
| 536 | month: string; |
| 537 | months: string[]; |
| 538 | groups: { |
| 539 | key: string; |
| 540 | label: string; |
| 541 | /** `coveredMicros`: what the plan's included usage, the trial, the open-source pool or g1t paid, not in `chargedMicros`. */ |
| 542 | /** `priceMicros`: usage at its price; `discountMicros`: what the account's discount took off it. */ |
| 543 | lines: { |
| 544 | kind: string; |
| 545 | count: number; |
| 546 | chargedMicros: number; |
| 547 | costMicros: number; |
| 548 | coveredMicros?: number; |
| 549 | priceMicros?: number; |
| 550 | discountMicros?: number; |
| 551 | /** On `Tax` and `Card processing fees` lines: what was paid with payments on top of what reached the balance. Never charged. */ |
| 552 | passedMicros?: number; |
| 553 | /** On a `Runner minutes, <machine>` line: the minutes charged, each job's time rounded up to the minute. */ |
| 554 | minutes?: number; |
| 555 | }[]; |
| 556 | chargedMicros: number; |
| 557 | priceMicros?: number; |
| 558 | discountMicros?: number; |
| 559 | }[]; |
| 560 | totals: { |
| 561 | chargedMicros: number; |
| 562 | paidMicros: number; |
| 563 | costMicros: number; |
| 564 | entries: number; |
| 565 | /** Usage at price, and what the discount took off: charged is the price less the discount and what paid for it. */ |
| 566 | priceMicros?: number; |
| 567 | discountMicros?: number; |
| 568 | /** The account's discount now, in percent; absent without one. */ |
| 569 | discountPercent?: number | null; |
| 570 | /** What paid for usage before it was charged, such as "Paid by g1t's open-source pool". */ |
| 571 | covered?: { source: "included" | "trial" | "oss_pool" | "given" | string; label: string; micros: number }[]; |
| 572 | /** Owed when the month closed but under the minimum charge: on the next invoice. */ |
| 573 | carriedMicros?: number; |
| 574 | /** Tax and card processing fees paid with the month's payments, on top of `paidMicros`. */ |
| 575 | taxMicros?: number; |
| 576 | cardFeeMicros?: number; |
| 577 | }; |
| 578 | }; |
| 579 | |
| 580 | export type MonthFigures = { |
| 581 | month: string; |
| 582 | /** Usage charged, after what paid for it first. */ |
| 583 | chargedMicros: number; |
| 584 | /** What usage cost g1t: never a workspace's own model provider. */ |
| 585 | costMicros: number; |
| 586 | paidMicros: number; |
| 587 | /** The plan's monthly price, paid. */ |
| 588 | plansMicros?: number; |
| 589 | /** What g1t gave at price (internal use, trials, the open-source pool, goodwill, covered). Not margin. */ |
| 590 | givenMicros?: number; |
| 591 | }; |
| 592 | |
| 593 | /** What g1t gave this month from one source. */ |
| 594 | export type GivenFigures = { source: "internal" | "trial" | "oss_pool" | "goodwill" | "covered" | string; label: string; micros: number; costMicros: number }; |
| 595 | |
| 596 | /** One internal workspace's use this month, and why it is not charged. */ |
| 597 | export type InternalUse = { workspace: string; reason: string; costMicros: number; entries: number }; |
| 598 | |
| 599 | export type SignalKind = "at_limit" | "near_ceiling" | "declined" | "growing" | "established" | "first_payment" | "high_spend" | "cost_over_revenue"; |
| 600 | |
| 601 | /** Why a workspace is worth reaching out to. */ |
| 602 | export type Signal = { |
| 603 | workspace: string; |
| 604 | kind: SignalKind; |
| 605 | detail: string; |
| 606 | valueMicros: number; |
| 607 | stage: string | null; |
| 608 | owner: string | null; |
| 609 | nextStep?: string | null; |
| 610 | /** When the next step is due, YYYY-MM-DD. */ |
| 611 | nextAt?: string | null; |
| 612 | }; |
| 613 | |
| 614 | /** One invoice g1t has sent, a workspace's or an enterprise's. */ |
| 615 | export type InvoiceSummary = { |
| 616 | invoiceId: string; |
| 617 | kind: "workspace" | "enterprise"; |
| 618 | account: string; |
| 619 | name: string; |
| 620 | reason: string; |
| 621 | period: string; |
| 622 | amountMicros: number; |
| 623 | status: string; |
| 624 | hostedUrl: string | null; |
| 625 | createdAt: string; |
| 626 | paidAt: string | null; |
| 627 | }; |
| 628 | |
| 629 | export type SalesStage = "none" | "lead" | "contacted" | "negotiating" | "won" | "lost" | "churn_risk"; |
| 630 | |
| 631 | export type SalesRecord = { |
| 632 | workspace: string; |
| 633 | stage: SalesStage | string; |
| 634 | owner: string | null; |
| 635 | nextStep: string | null; |
| 636 | nextAt: string | null; |
| 637 | notes: { id: string; text: string; by: string; createdAt: string }[]; |
| 638 | updatedAt: string | null; |
| 639 | }; |
| 640 | |
| 641 | export type Overview = { |
| 642 | month: string; |
| 643 | months: MonthFigures[]; |
| 644 | byKind: { kind: string; chargedMicros: number; costMicros: number }[]; |
| 645 | payingWorkspaces: number; |
| 646 | stopped: number; |
| 647 | nearCeiling: number; |
| 648 | declined: number; |
| 649 | openInvoicesMicros: number; |
| 650 | followUpsDue: number; |
| 651 | /** g1t's capped budgets for free usage, this month. */ |
| 652 | pools?: Pools | null; |
| 653 | /** Usage charged plus the plan's price paid, this month. */ |
| 654 | revenueMicros?: number; |
| 655 | activePlans?: number; |
| 656 | planMrrMicros?: number; |
| 657 | /** What g1t gave this month, by source, apart from its margin. */ |
| 658 | given?: GivenFigures[]; |
| 659 | /** g1t's own and Flagon's workspaces: what their use cost, and why they are not charged. */ |
| 660 | internal?: InternalUse[]; |
| 661 | openRequests?: number; |
| 662 | overages?: number; |
| 663 | openSpikes?: number; |
| 664 | }; |
| 665 | |
| 666 | /** A customer's Stripe billing page, for staff to send them. */ |
| 667 | export type BillingLink = { |
| 668 | /** One-time and short-lived, signed in already. */ |
| 669 | portalUrl: string; |
| 670 | /** The page's sign-in, which does not expire: the customer signs in by email. */ |
| 671 | loginUrl: string | null; |
| 672 | customerEmail: string | null; |
| 673 | expiresNote: string; |
| 674 | }; |
| 675 | |
| 676 | export type AdminAction = { id: string; account: string; action: string; detail: string; by: string; createdAt: string }; |
| 677 | |
| 678 | export type AccountDetail = { |
| 679 | summary: AccountSummary; |
| 680 | workspaces: Limit[]; |
| 681 | ledger: LedgerEntry[]; |
| 682 | audit: AdminAction[]; |
| 683 | }; |
| 684 | |
| 685 | /** Staff-only billing, for sudo.g1t.sh. Every change names who made it. */ |
| 686 | export interface BillingAdminApi { |
| 687 | accounts(query?: string): Promise<AccountSummary[]>; |
| 688 | account(id: string): Promise<Result<AccountDetail>>; |
| 689 | setTerms(id: string, terms: Terms, by: string): Promise<Result<PayingAccount>>; |
| 690 | /** Team on or off without charge, and the account's share of the pools. Needs a note. */ |
| 691 | setAllowances(id: string, allowances: Allowances, note: string, by: string): Promise<Result<PayingAccount>>; |
| 692 | /** A workspace's complimentary enrollment, if it ever had one. */ |
| 693 | complimentary(workspace: string): Promise<ComplimentaryStanding | null>; |
| 694 | /** |
| 695 | * Enrolls a workspace, or changes its terms from now on (the month's use is kept). Needs a note. |
| 696 | * `chargePastAllowance`: past the allowance, its own card is charged (employees, friends); otherwise work stops. |
| 697 | */ |
| 698 | setComplimentary( |
| 699 | workspace: string, |
| 700 | terms: { allowanceMicros: number; unlimited: boolean; feeCents: number; chargePastAllowance: boolean }, |
| 701 | note: string, |
| 702 | by: string, |
| 703 | ): Promise<Result<ComplimentaryStanding>>; |
| 704 | /** Ends an enrollment now: back to Free, its Stripe subscription canceled. */ |
| 705 | endComplimentary(workspace: string, note: string, by: string): Promise<Result<ComplimentaryStanding>>; |
| 706 | createEnterprise(name: string, workspaces: string[], by: string): Promise<Result<PayingAccount>>; |
| 707 | attach(workspace: string, account: string | null, by: string): Promise<Result<PayingAccount>>; |
| 708 | /** Credit for a workspace: promotional, goodwill or a refund; the owners are emailed. */ |
| 709 | credit(workspace: string, amountMicros: number, note: string, by: string, options?: CreditOptions): Promise<Result<LedgerEntry>>; |
| 710 | /** Every credit g1t gave, filtered, with each month's totals by kind. */ |
| 711 | credits(filter?: { workspace?: string | null; kind?: CreditKind | null; month?: string | null; by?: string | null }): Promise<AdminCredits>; |
| 712 | /** What is left of a credit, taken back, with why. */ |
| 713 | revokeCredit(id: string, note: string, by: string): Promise<Result<CreditGrant>>; |
| 714 | /** A test workspace's billing wiped, to start again as a new customer. Only on Stripe's test key; never comped or enterprise. Logged. */ |
| 715 | resetBilling(workspace: string, confirm: string, note: string, by: string): Promise<Result<BillingReset>>; |
| 716 | /** |
| 717 | * Test-mode Stripe data made inert before the live key, history kept: one |
| 718 | * workspace (any but an enterprise's), or every workspace not comped, not an |
| 719 | * enterprise's and not excluded (default syntaqx, flagon-io). Refused on a live key. Logged. |
| 720 | */ |
| 721 | detachTestStripe(args: DetachTestStripeArgs): Promise<Result<TestStripeDetach>>; |
| 722 | /** The workspace's Stripe billing page, to send to the customer. Logged. */ |
| 723 | billingLink(workspace: string, by: string): Promise<Result<BillingLink>>; |
| 724 | /** Where billing stands with Stripe; with `setup`, registers the webhook first. */ |
| 725 | /** Stripe's state for billing; `fix` enables the destination and adds missing events first. */ |
| 726 | stripe(fix?: boolean, by?: string): Promise<StripeStatus>; |
| 727 | /** Where an enterprise's invoices go; makes its Stripe customer. */ |
| 728 | enterpriseBilling(id: string, email: string, by: string): Promise<Result<PayingAccount>>; |
| 729 | /** The enterprise's billing address and tax ID, on its Stripe customer: Stripe Tax works its invoices out from them. */ |
| 730 | enterpriseAddress(id: string, address: PostalAddress, taxIdType: string | null, taxId: string | null, by: string): Promise<Result<boolean>>; |
| 731 | /** Sends an enterprise its invoice now, for what its workspaces owe. */ |
| 732 | invoiceEnterprise(id: string, by: string): Promise<Result<EnterpriseInvoice>>; |
| 733 | /** Exactly these workspaces' accounts, such as one page of the list. */ |
| 734 | accountsFor(workspaces: string[]): Promise<AccountSummary[]>; |
| 735 | /** Every workspace worth reaching out to, most urgent first. */ |
| 736 | signals(): Promise<Signal[]>; |
| 737 | /** The business at a glance. */ |
| 738 | overview(): Promise<Overview>; |
| 739 | /** A workspace's sales record. */ |
| 740 | sales(workspace: string): Promise<SalesRecord>; |
| 741 | setSales(workspace: string, record: { stage: string; owner?: string | null; nextStep?: string | null; nextAt?: string | null }, by: string): Promise<Result<SalesRecord>>; |
| 742 | addNote(workspace: string, text: string, by: string): Promise<Result<SalesRecord>>; |
| 743 | /** A workspace's invoices from g1t, for staff. */ |
| 744 | workspaceInvoices(workspace: string): Promise<WorkspaceInvoice[]>; |
| 745 | /** Every invoice g1t has sent, newest first. */ |
| 746 | allInvoices(filter?: { status?: string; month?: string }): Promise<InvoiceSummary[]>; |
| 747 | /** Every change made in sudo and by Stripe, newest first, 100 at a time. */ |
| 748 | audit(filter?: { by?: string; action?: string; before?: string }): Promise<AdminAction[]>; |
| 749 | /** Limit and overage requests, with each workspace's history; `open` by default. */ |
| 750 | limitRequests(status?: "open" | "approved" | "declined" | "all"): Promise<LimitRequestReview[]>; |
| 751 | /** Approve (at the amount asked, or another) or decline; the owner is told in the app and by email. */ |
| 752 | decideLimitRequest(id: string, decision: "approve" | "decline", amountMicros: number | null, note: string, by: string): Promise<Result<LimitRequest>>; |
| 753 | /** The Overages queue. */ |
| 754 | overages(): Promise<Overage[]>; |
| 755 | /** A goodwill credit; no amount is the one-click credit. Larger, or a second in 12 months, needs a reason. `requestKey`, made once per form, makes a double click or a retry one credit. */ |
| 756 | goodwill( |
| 757 | workspace: string, |
| 758 | amountMicros: number | null, |
| 759 | reason: string, |
| 760 | by: string, |
| 761 | day?: string | null, |
| 762 | requestKey?: string | null, |
| 763 | ): Promise<Result<LedgerEntry>>; |
| 764 | /** Workspaces spending in the last day, fastest first. */ |
| 765 | velocity(): Promise<Velocity[]>; |
| 766 | /** Money that reached g1t outside the card pages, such as a bank transfer: entered as a payment. */ |
| 767 | recordPayment(workspace: string, amountMicros: number, reference: string, note: string, by: string): Promise<Result<LedgerEntry>>; |
| 768 | /** Costs & margin: Cloudflare's bill against what g1t charged, over the last `days` (7 to 90, 30 by default). */ |
| 769 | costs(days?: number): Promise<CostsReport>; |
| 770 | /** The open margin alerts, for the banner on every page. */ |
| 771 | costAlerts(): Promise<MarginAlert[]>; |
| 772 | /** g1t's own spend against its caps: the daily breaker and comped budgets. */ |
| 773 | spendCaps(): Promise<SpendCaps>; |
| 774 | /** Lets compute start again for the rest of today (UTC) after the daily breaker; needs a note. */ |
| 775 | liftBreaker(note: string, by: string): Promise<Result<SpendCaps>>; |
| 776 | /** Platform pauses, the last hour of platform usage, the month so far and the last day's breaches (billing's platform.rs). */ |
| 777 | platformGuard(): Promise<PlatformGuard>; |
| 778 | /** Pauses or resumes one level across g1t; needs a note, recorded in the audit log. */ |
| 779 | setPause(level: PauseLevel, paused: boolean, note: string, by: string): Promise<Result<PlatformGuard>>; |
| 780 | /** Approve or reject a price proposal; a rejection needs a note. An approved rise waits out the notice period. */ |
| 781 | decideProposal(id: string, decision: "approve" | "reject", note: string, by: string): Promise<Result<PriceProposal>>; |
| 782 | setCostSettings(settings: CostSettings, by: string): Promise<Result<CostSettings>>; |
| 783 | setCostMapping(mapping: CostMappingInput, by: string): Promise<Result<CostMapping>>; |
| 784 | /** Reads Cloudflare's bill and reconciles now, as the daily run does. */ |
| 785 | runCosts(by: string): Promise<Result<CostsRun>>; |
| 786 | } |
| 787 | |
| 788 | /** How much a workspace has earned g1t's trust with money. */ |
| 789 | export type Trust = "new" | "paid" | "established" | "reviewed" | "internal"; |
| 790 | |
| 791 | /** |
| 792 | * How far a workspace's unpaid usage has gone this month, and where its |
| 793 | * work stops: past `ceilingMicros`, no new sandboxes, builds or app |
| 794 | * requests. Usage counts at its cost to g1t or its charge, whichever is |
| 795 | * more, so it counts while g1t is free too. |
| 796 | */ |
| 797 | export type Limit = { |
| 798 | workspace: string; |
| 799 | /** The account that pays: the workspace's own (`ws_<slug>`), or its enterprise's. */ |
| 800 | account: string; |
| 801 | accountName: string; |
| 802 | trust: Trust; |
| 803 | exposureMicros: number; |
| 804 | /** The lower of g1t's ceiling and the owner's spend limit; null for g1t's own. */ |
| 805 | ceilingMicros: number | null; |
| 806 | trustCeilingMicros: number | null; |
| 807 | spendLimitMicros: number | null; |
| 808 | state: "ok" | "warning" | "stopped"; |
| 809 | message: string | null; |
| 810 | /** |
| 811 | * Charged this month, which the spend limit is measured against: usage at |
| 812 | * price less the discount, included usage, the trial, pools and credit, |
| 813 | * with usage metered through the month counted on the same terms. The |
| 814 | * same number as the month's `UsageTotals.chargedMicros`. |
| 815 | */ |
| 816 | spentMicros?: number; |
| 817 | /** True while the owners have not chosen a limit, so the automatic one applies: $200, or twice last month's spend. */ |
| 818 | defaultSpendLimit?: boolean; |
| 819 | /** The most owners may set their own limit to without asking: the highest ceiling ever, plus what is prepaid. */ |
| 820 | availableMicros?: number | null; |
| 821 | /** How the ceiling grows from here, in a sentence. */ |
| 822 | growth?: string | null; |
| 823 | /** Paid in advance and not used yet; raises what can be used before work stops by as much. */ |
| 824 | prepaidMicros?: number; |
| 825 | /** The highest ceiling the workspace has had. */ |
| 826 | maxCeilingMicros?: number | null; |
| 827 | /** The most owners may raise the limit to themselves, once: twice the highest ceiling. Null once used. */ |
| 828 | raiseOnceMicros?: number | null; |
| 829 | /** When the one-time raise was used. */ |
| 830 | raisedAt?: string | null; |
| 831 | /** A paid workspace's first billing cycle, on the starting ceiling. */ |
| 832 | firstMonth?: boolean; |
| 833 | /** The budget's alerts, in percent of the spend limit: some of 50, 75, 90 and 100. */ |
| 834 | alertLevels?: number[]; |
| 835 | /** Whether usage pauses at the spend limit (the default); off, it only alerts. */ |
| 836 | pauseAtLimit?: boolean; |
| 837 | /** An HTTPS address told of each budget alert. */ |
| 838 | budgetWebhook?: string | null; |
| 839 | }; |
| 840 | |
| 841 | /** One metered unit: what it costs g1t and what it is sold at; the price follows the cost. */ |
| 842 | export type Price = { |
| 843 | meter: |
| 844 | | "sandbox_second" |
| 845 | | "build_second" |
| 846 | | "app_requests" |
| 847 | | "app_cpu" |
| 848 | | "app_month" |
| 849 | | "custom_domain_month" |
| 850 | | "private_storage" |
| 851 | | "embedding_tokens" |
| 852 | | "scan_cpu" |
| 853 | | "scan_rows" |
| 854 | | string; |
| 855 | title: string; |
| 856 | unit: string; |
| 857 | costMicros: number; |
| 858 | markupPercent: number; |
| 859 | priceMicros: number; |
| 860 | /** `list`: Cloudflare's published price. `cloudflare`: measured from Cloudflare's bill. */ |
| 861 | source: "list" | "cloudflare" | string; |
| 862 | checkedAt: string | null; |
| 863 | updatedAt: string; |
| 864 | }; |
| 865 | |
| 866 | export type PriceChange = { |
| 867 | meter: string; |
| 868 | oldCostMicros: number; |
| 869 | newCostMicros: number; |
| 870 | markupPercent: number; |
| 871 | /** The markup before, when the change was to the markup rather than the cost. */ |
| 872 | oldMarkupPercent?: number; |
| 873 | reason: string; |
| 874 | createdAt: string; |
| 875 | /** When a change still to come takes effect: a rise is announced before it is charged. */ |
| 876 | effectiveAt?: string; |
| 877 | }; |
| 878 | |
| 879 | export type PriceBook = { |
| 880 | prices: Price[]; |
| 881 | changes: PriceChange[]; |
| 882 | /** Retired with the models g1t no longer runs; still sent. */ |
| 883 | modelMarginPercent: number; |
| 884 | /** Every plan, as sold now. */ |
| 885 | plans?: FeaturePlan[]; |
| 886 | /** What is free, and the capped budgets that pay for it. */ |
| 887 | free?: FreeTier | null; |
| 888 | }; |
| 889 | |
| 890 | /** One kind of meter's usage this month, from `usage_meters`. */ |
| 891 | export type MeterUsage = { |
| 892 | /** `agents`, `builds`, `requests`, `domains`, `git_storage` or `search_scans`. */ |
| 893 | key: string; |
| 894 | label: string; |
| 895 | /** At price (cost plus 20%, on the account's terms), before what paid for it. */ |
| 896 | micros: number; |
| 897 | /** How much, when it is known: `12 runs`, `41 build minutes`. */ |
| 898 | quantity?: string | null; |
| 899 | }; |
| 900 | |
| 901 | /** What g1t gives without a plan; each is paid for by a capped budget. */ |
| 902 | export type FreeTier = { |
| 903 | /** Each new workspace's trial credit, once. */ |
| 904 | trialWorkspaceMicros: number; |
| 905 | /** Trial grants each month, in all; new trials wait when it is spent. */ |
| 906 | trialMonthlyPoolMicros: number; |
| 907 | /** g1t's open-source pool each month, and any one repository's share. */ |
| 908 | ossPoolMicros: number; |
| 909 | ossRepoMicros: number; |
| 910 | /** Private repository storage free for every workspace. Past it, the plan pays; a free workspace's pushes stop. */ |
| 911 | freePrivateStorageBytes: number; |
| 912 | /** Days of audit log a free workspace keeps. */ |
| 913 | auditRetentionDays: number; |
| 914 | /** Days of audit log the g1t plan keeps, and g1t's own and enterprise workspaces; longer by arrangement. */ |
| 915 | planAuditRetentionDays?: number; |
| 916 | /** The smallest amount a card is charged when a month closes; less carries over. */ |
| 917 | minChargeMicros: number; |
| 918 | /** Git operations free for every workspace each month. Past it, the plan pays; a free workspace is slowed down. */ |
| 919 | gitOperationsIncluded?: number; |
| 920 | /** A new paid workspace's ceiling in its first month. */ |
| 921 | paidStartCeilingMicros?: number; |
| 922 | /** The most a one-click goodwill credit can cost g1t. */ |
| 923 | overageForgiveCostMicros?: number; |
| 924 | }; |
| 925 | |
| 926 | /** |
| 927 | * A workspace's trial credit: one grant per workspace, made the first time |
| 928 | * it uses something, out of a pool that resets each calendar month. Mirrors |
| 929 | * `Trial` in `crates/contracts/src/billing.rs`. |
| 930 | */ |
| 931 | export type Trial = { |
| 932 | open: boolean; |
| 933 | usedMicros: number; |
| 934 | limitMicros: number; |
| 935 | /** No longer used: trials do not end on a date. */ |
| 936 | endsAt: string | null; |
| 937 | /** Why it is closed: `off`, `used` (this workspace's grant is spent) or `pool` (this month's are given out). */ |
| 938 | reason: "off" | "ended" | "used" | "pool" | null; |
| 939 | /** Whether the workspace has its grant already. */ |
| 940 | granted?: boolean; |
| 941 | /** With `pool`: when new trials start again, the first of next month. */ |
| 942 | waitsUntil?: string | null; |
| 943 | }; |
| 944 | |
| 945 | /** |
| 946 | * What a workspace has: the g1t plan (`plan`), and Security and quality |
| 947 | * (`security`), which comes with the plan at no price of its own. Deployments |
| 948 | * are part of the plan too; `has_feature` for either answers whether the |
| 949 | * workspace has the plan. Mirrors `Feature` in `crates/contracts/src/billing.rs`. |
| 950 | */ |
| 951 | export type Feature = "plan" | "deployments" | "security"; |
| 952 | |
| 953 | /** |
| 954 | * What deployments cost g1t, in millionths of a dollar: fallbacks for when |
| 955 | * billing's price book cannot be read. Not an allowance: on the plan every |
| 956 | * unit is metered from the first, at cost plus 20%, and drawn from the |
| 957 | * plan's included usage first. Projects, previews and the apps behind them |
| 958 | * are not metered at all. Mirrors `deployment_costs`. |
| 959 | */ |
| 960 | export const DEPLOYMENT_COSTS = { |
| 961 | microsPerMillionRequests: 300_000, |
| 962 | microsPerMillionCpuMs: 20_000, |
| 963 | /** One second of a build's sandbox: a fallback; billing charges the price book's `build_second`. */ |
| 964 | microsPerBuildSecond: 15, |
| 965 | /** One custom domain for a month. */ |
| 966 | microsPerDomainMonth: 100_000, |
| 967 | /** |
| 968 | * Container apps, at Cloudflare Containers' list prices: a vCPU-second |
| 969 | * $0.00002, a GiB-second of memory $0.0000025, a GB-second of disk |
| 970 | * $0.00000007, the Durable Object in front of each instance while it |
| 971 | * runs (128 MB at $12.50 per million GB-seconds), and a GB of egress |
| 972 | * at $0.05, the most Cloudflare charges for one anywhere (Oceania, Korea |
| 973 | * and Taiwan; $0.025 in North America and Europe), since g1t cannot |
| 974 | * tell where a container's traffic went. |
| 975 | */ |
| 976 | container: { |
| 977 | vcpuSecond: 20, |
| 978 | memoryGibSecond: 2.5, |
| 979 | diskGbSecond: 0.07, |
| 980 | instanceSecond: 1.5625, |
| 981 | egressGb: 50_000, |
| 982 | }, |
| 983 | } as const; |
| 984 | |
| 985 | export type FeaturePlan = { |
| 986 | feature: Feature; |
| 987 | title: string; |
| 988 | /** Charged every month while the plan is on, in cents, excluding tax: all of it, with no card fee on top. */ |
| 989 | monthlyCents: number; |
| 990 | /** What the price includes, one line each. */ |
| 991 | includes: string[]; |
| 992 | /** How usage past the allowance is charged. */ |
| 993 | overage: string; |
| 994 | }; |
| 995 | |
| 996 | export type SubscriptionStatus = "active" | "canceling" | "past_due" | "canceled"; |
| 997 | |
| 998 | export type Subscription = { |
| 999 | feature: Feature; |
| 1000 | status: SubscriptionStatus; |
| 1001 | /** RFC 3339: when the period paid for ends. */ |
| 1002 | periodEnd: string | null; |
| 1003 | startedBy: string; |
| 1004 | startedAt: string; |
| 1005 | }; |
| 1006 | |
| 1007 | /** A feature as a workspace sees it. */ |
| 1008 | export type FeatureState = { |
| 1009 | plan: FeaturePlan; |
| 1010 | subscription: Subscription | null; |
| 1011 | /** Whether the feature works for the workspace now. */ |
| 1012 | on: boolean; |
| 1013 | /** On without a plan: comped terms, or given by g1t. Nothing to pay or turn off. */ |
| 1014 | included?: boolean; |
| 1015 | }; |
| 1016 | |
| 1017 | export interface BillingApi { |
| 1018 | status(): Promise<BillingStatus>; |
| 1019 | /** Members of the workspace only. */ |
| 1020 | account(workspace: string, viewer: Viewer): Promise<Result<BillingAccount>>; |
| 1021 | /** Newest first. Members of the workspace only. */ |
| 1022 | ledger(workspace: string, viewer: Viewer): Promise<Result<LedgerEntry[]>>; |
| 1023 | /** Credits from g1t, newest first, with what is left of each. Members only. */ |
| 1024 | credits(workspace: string, viewer: Viewer): Promise<Result<Credits>>; |
| 1025 | /** A month of the ledger, grouped by `day` (default) or `project`. Members only. */ |
| 1026 | statement(workspace: string, viewer: Viewer, month?: string | null, group?: "day" | "project"): Promise<Result<Statement>>; |
| 1027 | /** One statement line's entries, 50 at a time; `before` is the last id seen. */ |
| 1028 | statementEntries( |
| 1029 | workspace: string, |
| 1030 | viewer: Viewer, |
| 1031 | filter: { month: string; kind: string; day?: string | null; project?: string | null; before?: string | null }, |
| 1032 | ): Promise<Result<LedgerEntry[]>>; |
| 1033 | /** What the workspace's agents cost since `since`, broken down. Members only. */ |
| 1034 | usage(workspace: string, viewer: Viewer, since: string): Promise<Result<Usage>>; |
| 1035 | /** |
| 1036 | * Prepays usage ($25 at least) and returns the page to send the person to: |
| 1037 | * by card with 3-D Secure, or by bank transfer from $1,000. Owners only. |
| 1038 | * The payment's id comes back to `returnUrl` as `session`. |
| 1039 | */ |
| 1040 | checkout( |
| 1041 | actor: User, |
| 1042 | workspace: string, |
| 1043 | amountCents: number, |
| 1044 | returnUrl: string, |
| 1045 | method?: "card" | "bank_transfer", |
| 1046 | ): Promise<Result<{ url: string }>>; |
| 1047 | /** |
| 1048 | * Stripe's hosted billing page for the workspace: card, invoices, billing |
| 1049 | * email and address. g1t never handles card numbers. Owners only. |
| 1050 | */ |
| 1051 | billingPortal(actor: User, workspace: string, returnUrl: string): Promise<Result<{ url: string }>>; |
| 1052 | /** Credits a payment once the processor says it was made. Safe to repeat. */ |
| 1053 | confirm(workspace: string, viewer: Viewer, session: string): Promise<Result<BillingAccount>>; |
| 1054 | /** A workspace's free trial allowance; `exempt` workspaces are open anyway. */ |
| 1055 | trial(workspace: string, exempt: string[]): Promise<Trial>; |
| 1056 | /** Every paid feature and the workspace's plan for each. Members only. */ |
| 1057 | features(workspace: string, viewer: Viewer): Promise<Result<FeatureState[]>>; |
| 1058 | /** |
| 1059 | * Starts the card page for a feature's monthly plan. Owners only. The |
| 1060 | * page's id comes back to `returnUrl` as `session`. |
| 1061 | */ |
| 1062 | subscribe(actor: User, workspace: string, feature: Feature, returnUrl: string): Promise<Result<{ url: string }>>; |
| 1063 | /** Turns the feature on once the plan is paid for. Safe to repeat. */ |
| 1064 | confirmSubscription(workspace: string, viewer: Viewer, session: string): Promise<Result<FeatureState>>; |
| 1065 | /** Ends a plan at the end of its period, or (`resume`) takes that back. Owners only. */ |
| 1066 | cancelSubscription(actor: User, workspace: string, feature: Feature, resume?: boolean): Promise<Result<FeatureState>>; |
| 1067 | /** A complimentary workspace starts the plan on its own subscription; nothing changes until the first payment succeeds. Owners and billing managers. */ |
| 1068 | convertToPaid(actor: User, workspace: string, returnUrl: string): Promise<Result<Conversion>>; |
| 1069 | /** Which of the workspaces are free (on no paid plan); none where payments are not set up. */ |
| 1070 | freeWorkspaces(workspaces: string[]): Promise<string[]>; |
| 1071 | /** Whether a feature works for a workspace now; a failure with the reason when not. */ |
| 1072 | hasFeature(workspace: string, feature: Feature): Promise<Result<boolean>>; |
| 1073 | /** |
| 1074 | * Usage past a plan's allowance, charged from credit at cost plus the |
| 1075 | * margin, once per `reference`. False if it was charged before. |
| 1076 | */ |
| 1077 | chargeFeature(charge: { |
| 1078 | workspace: string; |
| 1079 | feature: Feature; |
| 1080 | costMicros: number; |
| 1081 | description: string; |
| 1082 | repo?: string | null; |
| 1083 | reference: string; |
| 1084 | /** For a build: how long it ran, so the plan's included build time pays for what it can. */ |
| 1085 | buildSeconds?: number | null; |
| 1086 | }): Promise<Result<boolean>>; |
| 1087 | /** |
| 1088 | * What a source cost g1t so far this month, so the workspace's limit |
| 1089 | * counts it now. Replaces the last report. Billing charges `context` |
| 1090 | * and `security` itself once the month is over; `deployments` charges |
| 1091 | * its own. `context` is search embeddings (services/artifacts) and |
| 1092 | * `telemetry` is observability ingest past the free amount |
| 1093 | * (services/telemetry), both at cost. |
| 1094 | */ |
| 1095 | notePending( |
| 1096 | workspace: string, |
| 1097 | source: "deployments" | "domains" | "context" | "security" | "telemetry", |
| 1098 | costMicros: number, |
| 1099 | /** How much of it, for the Billing page: `1.2 million requests and 3.4 million CPU ms`. */ |
| 1100 | detail?: string | null, |
| 1101 | /** |
| 1102 | * The month (`YYYY-MM`, UTC) the total belongs to, read when it was |
| 1103 | * worked out. Billing takes this month, or the month before while its |
| 1104 | * figure for the source is not charged and the month is not closed. |
| 1105 | * Left out: the month the report arrives in. |
| 1106 | */ |
| 1107 | month?: string | null, |
| 1108 | ): Promise<boolean>; |
| 1109 | /** |
| 1110 | * This month's usage, one line per kind of meter, at what it is charged |
| 1111 | * before the plan's included usage or a pool paid for it. Members only. |
| 1112 | */ |
| 1113 | usageMeters(workspace: string, viewer: Viewer): Promise<Result<MeterUsage[]>>; |
| 1114 | /** What the workspace may do now: its plan, caps, pause, trial, and what the plan gives it. */ |
| 1115 | entitlements(workspace: string): Promise<Entitlements>; |
| 1116 | /** |
| 1117 | * Holds a start's estimated cost before the work starts. A failure's code says why not: |
| 1118 | * `paused`, `limit`, `not_paid`, `trial_used` or `oss_pool_empty`, with a message for the owner. |
| 1119 | */ |
| 1120 | reserve(reservation: { |
| 1121 | workspace: string; |
| 1122 | repo: RepoPath; |
| 1123 | public: boolean; |
| 1124 | kind: ComputeKind; |
| 1125 | /** The most the work is expected to cost g1t, before the margin. */ |
| 1126 | estimateMicros: number; |
| 1127 | }): Promise<Result<ReservationHeld>>; |
| 1128 | /** Releases a reservation's hold with what the work cost g1t, before the margin. Safe to repeat. */ |
| 1129 | settle(reservationId: string, actualMicros: number): Promise<Result<boolean>>; |
| 1130 | /** Stripe's page to save and verify a card (3-D Secure, never charged). Owners only. */ |
| 1131 | cardCheck(actor: User, workspace: string, returnUrl: string): Promise<Result<{ url: string }>>; |
| 1132 | /** Records the card check once Stripe says it passed, and grants the trial if it can. Safe to repeat. */ |
| 1133 | confirmCardCheck(workspace: string, viewer: Viewer, session: string): Promise<Result<Entitlements>>; |
| 1134 | /** An owner asks for a higher limit, or for help with usage past what was meant. */ |
| 1135 | requestLimit( |
| 1136 | actor: User, |
| 1137 | workspace: string, |
| 1138 | request: { kind: "limit" | "overage"; amountMicros: number; reason: string; expectedMonthlyMicros: number }, |
| 1139 | ): Promise<Result<LimitRequest>>; |
| 1140 | /** The workspace's requests and their answers, newest first. Members only. */ |
| 1141 | limitRequests(workspace: string, viewer: Viewer): Promise<Result<LimitRequest[]>>; |
| 1142 | /** An owner's answer to a spend spike: keep going for 24 hours, or stop. */ |
| 1143 | confirmSpike(actor: User, workspace: string, keepGoing: boolean): Promise<Result<Entitlements>>; |
| 1144 | /** Every metered price and the recent changes. Public. */ |
| 1145 | prices(): Promise<PriceBook>; |
| 1146 | /** A workspace's limit, for its members. */ |
| 1147 | limit(workspace: string, viewer: Viewer): Promise<Result<Limit>>; |
| 1148 | /** The same, for the services that enforce it. */ |
| 1149 | checkLimit(workspace: string): Promise<Result<Limit>>; |
| 1150 | /** |
| 1151 | * The owners' own monthly limit, up to what is available; null goes back |
| 1152 | * to the default, and `useFullLimit` uses everything available. Owners only. |
| 1153 | */ |
| 1154 | setSpendLimit( |
| 1155 | actor: User, |
| 1156 | workspace: string, |
| 1157 | spendLimitMicros: number | null, |
| 1158 | useFullLimit?: boolean, |
| 1159 | /** Use the one-time raise: up to twice the highest ceiling, once per workspace. */ |
| 1160 | raiseOnce?: boolean, |
| 1161 | ): Promise<Result<Limit>>; |
| 1162 | /** The workspace's invoices from g1t, newest first. Owners and billing managers only. */ |
| 1163 | invoices(workspace: string, viewer: Viewer): Promise<Result<WorkspaceInvoice[]>>; |
| 1164 | /** |
| 1165 | * How long a sandbox ran for a workspace, reported when it stops. Its |
| 1166 | * cost is recorded and every second is charged, from the first. False if |
| 1167 | * `reference` was recorded before. |
| 1168 | */ |
| 1169 | recordSandbox(usage: { |
| 1170 | workspace: string; |
| 1171 | seconds: number; |
| 1172 | description: string; |
| 1173 | repo?: string | null; |
| 1174 | reference: string; |
| 1175 | /** What ran; checks, workflows and the merge queue on public repositories may use the open-source pool. */ |
| 1176 | kind?: ComputeKind | null; |
| 1177 | /** vCPU-seconds used, when the sandbox can tell: the run is priced on its own CPU. */ |
| 1178 | cpuSeconds?: number | null; |
| 1179 | /** The reservation it started under, settled with this cost. */ |
| 1180 | reservationId?: string | null; |
| 1181 | /** It ran on one of the workspace's self-hosted runners: its minutes go on usage at $0. */ |
| 1182 | selfHosted?: boolean; |
| 1183 | /** The machine it ran on, by label (`g1t-4core`); absent, the standard one. */ |
| 1184 | instance?: string | null; |
| 1185 | }): Promise<Result<boolean>>; |
| 1186 | /** Usage over a range of days (`YYYY-MM-DD`, both included), at price, by product, meter, project and day. Members only. */ |
| 1187 | usageReport( |
| 1188 | workspace: string, |
| 1189 | viewer: Viewer, |
| 1190 | range: { from: string; until: string; products?: string[]; projects?: string[] }, |
| 1191 | ): Promise<Result<UsageReport>>; |
| 1192 | /** The monthly budget: the spend limit, its alerts, whether usage pauses at 100%, and a webhook. Owners only. */ |
| 1193 | setBudget( |
| 1194 | actor: User, |
| 1195 | workspace: string, |
| 1196 | budget: { amountMicros: number | null; alerts: number[]; pauseAtLimit: boolean; webhook: string | null; keepLimit?: boolean }, |
| 1197 | ): Promise<Result<Limit>>; |
| 1198 | /** Invoice details from the Stripe customer, the default payment method, invoices and the next invoice: owners and billing managers. Any other member gets the next invoice only. */ |
| 1199 | billingDetails(workspace: string, viewer: Viewer): Promise<Result<BillingDetails>>; |
| 1200 | /** Saves invoice details on the Stripe customer; absent fields stay, empty clears. Owners only. */ |
| 1201 | setBillingDetails(actor: User, workspace: string, details: BillingDetailsInput): Promise<Result<BillingDetails>>; |
| 1202 | } |
| 1203 | |
| 1204 | |
| 1205 | /** One slice of usage: what it was for, what it cost, how many runs. */ |
| 1206 | export type UsageSlice = { key: string; micros: number; runs: number }; |
| 1207 | |
| 1208 | /** What a workspace's agents cost over a period. */ |
| 1209 | export type Usage = { |
| 1210 | since: string; |
| 1211 | /** Charged, including g1t's margin. */ |
| 1212 | spentMicros: number; |
| 1213 | /** What g1t's usage came to at price, less what was charged: the plan's included usage, the trial, a pool or a free period paid it. Usage at price is `spentMicros` plus this. */ |
| 1214 | coveredMicros?: number; |
| 1215 | /** What the account's discount took off the price; usage at price is spent + covered + this. */ |
| 1216 | discountMicros?: number; |
| 1217 | /** The account's discount now, in percent; with one, the slices are at price. */ |
| 1218 | discountPercent?: number | null; |
| 1219 | /** Usage at price: spent + covered + discount, from the same ledger lines. The one usage figure every page shows. */ |
| 1220 | priceMicros?: number; |
| 1221 | /** What g1t's model provider charged, before the margin. */ |
| 1222 | costMicros: number; |
| 1223 | /** What runs on the workspace's own provider cost there, estimated. Not charged by g1t. */ |
| 1224 | providerMicros: number; |
| 1225 | /** What the runs used, at cost: g1t's models and the workspace's own provider together. */ |
| 1226 | usedMicros: number; |
| 1227 | /** g1t charges nothing for now; the slices then measure usage at cost. */ |
| 1228 | free: boolean; |
| 1229 | runs: number; |
| 1230 | /** Spend per day and task, keyed `YYYY-MM-DD/task`. */ |
| 1231 | byDay: UsageSlice[]; |
| 1232 | byTask: UsageSlice[]; |
| 1233 | byRepo: UsageSlice[]; |
| 1234 | /** Keyed `namespace/name#number`. */ |
| 1235 | byPull: UsageSlice[]; |
| 1236 | byModel: UsageSlice[]; |
| 1237 | /** Credit bought in the period. */ |
| 1238 | addedMicros: number; |
| 1239 | }; |
| 1240 | |
| 1241 | /** One of g1t's products (a "bucket") on one day. Money in micros. */ |
| 1242 | export type CostDay = { day: string; bucket: string; cfCostMicros: number; ownCostMicros: number; valueMicros: number; cashMicros: number }; |
| 1243 | |
| 1244 | /** One product over the range: what customers were charged at price against what it cost. */ |
| 1245 | export type ProductMargin = { |
| 1246 | bucket: string; |
| 1247 | title: string; |
| 1248 | /** Cloudflare's bill, or g1t's own figure where Cloudflare does not bill it (`costSource`). */ |
| 1249 | costMicros: number; |
| 1250 | cfCostMicros: number; |
| 1251 | ownCostMicros: number; |
| 1252 | valueMicros: number; |
| 1253 | marginMicros: number; |
| 1254 | marginPercent: number | null; |
| 1255 | costSource: "cloudflare" | "ledger" | string; |
| 1256 | /** Running g1t, paid for by the plan. */ |
| 1257 | overhead: boolean; |
| 1258 | }; |
| 1259 | |
| 1260 | /** All of g1t: money in (usage and the plan) against every cost. */ |
| 1261 | export type OverallMargin = { |
| 1262 | usageMicros: number; |
| 1263 | plansMicros: number; |
| 1264 | costMicros: number; |
| 1265 | marginMicros: number; |
| 1266 | marginPercent: number | null; |
| 1267 | /** Of costMicros, what went on usage g1t gave away on purpose: comped workspaces, free periods, the trial and the open-source pool. */ |
| 1268 | givenMicros?: number; |
| 1269 | /** Money in against costMicros - givenMicros. */ |
| 1270 | soldMarginMicros?: number; |
| 1271 | soldMarginPercent?: number | null; |
| 1272 | /** Usage sold: usageMicros against what that usage cost, less what was given. */ |
| 1273 | usageCostMicros?: number; |
| 1274 | usageMarginMicros?: number; |
| 1275 | usageMarginPercent?: number | null; |
| 1276 | /** Running g1t: plansMicros against the platform's cost, less its given share. */ |
| 1277 | runningCostMicros?: number; |
| 1278 | /** Cost no mapping names, less its given share. */ |
| 1279 | unmappedCostMicros?: number; |
| 1280 | /** givenMicros by why. Free is free periods, free allowances and overruns g1t covered. */ |
| 1281 | givenCompedMicros?: number; |
| 1282 | givenFreeMicros?: number; |
| 1283 | givenTrialMicros?: number; |
| 1284 | givenPoolMicros?: number; |
| 1285 | /** What discounts on an account's terms took below cost plus the margin: given, not margin lost. */ |
| 1286 | givenDiscountMicros?: number; |
| 1287 | /** Credits from g1t spent on usage, by kind: given, never money in. Refunds come off money in instead. */ |
| 1288 | givenCreditPromotionalMicros?: number; |
| 1289 | givenCreditGoodwillMicros?: number; |
| 1290 | /** What testing resets wiped that g1t paid for: the usage still happened, so its cost is given, never a leak. */ |
| 1291 | givenResetMicros?: number; |
| 1292 | /** Credits over the range: given (every kind), spent on usage, and refunds' money given back. */ |
| 1293 | creditsGivenMicros?: number; |
| 1294 | creditsUsedMicros?: number; |
| 1295 | creditsRefundedMicros?: number; |
| 1296 | /** costMicros by who g1t pays: Cloudflare's bill (billed, after included allowances) and model providers (tokens, not on Cloudflare's bill). */ |
| 1297 | /** What the plan's included usage paid for, at price: money in for usage, paid out of plansMicros. */ |
| 1298 | includedMicros?: number; |
| 1299 | cloudflareCostMicros?: number; |
| 1300 | modelsCostMicros?: number; |
| 1301 | /** Tax collected with payments over the range, net of refunds: owed to tax authorities, never cash or revenue. */ |
| 1302 | taxCollectedMicros?: number; |
| 1303 | /** Card processing fees passed on with card payments, net of refunds: they pay Stripe's fee, not revenue. */ |
| 1304 | cardFeesMicros?: number; |
| 1305 | /** What workspaces were charged while payments were not live (Stripe's test mode): given, never money in. */ |
| 1306 | givenUnpaidMicros?: number; |
| 1307 | /** Cloudflare's subscriptions over the range: each day's share of the billing cycle it is in. */ |
| 1308 | subscriptionsMicros?: number; |
| 1309 | /** What AI Gateway priced g1t's own provider traffic at over the range, beside the ledger's model cost. */ |
| 1310 | gatewayCostMicros?: number; |
| 1311 | }; |
| 1312 | |
| 1313 | /** A count, cost or leak that does not add up. */ |
| 1314 | export type CostDrift = { |
| 1315 | bucket: string; |
| 1316 | title: string; |
| 1317 | kind: "count" | "cost" | "leak" | string; |
| 1318 | ours: number; |
| 1319 | cloudflare: number; |
| 1320 | deltaPercent: number | null; |
| 1321 | detail: string; |
| 1322 | foundAt: string; |
| 1323 | }; |
| 1324 | |
| 1325 | export type MarginAlert = { |
| 1326 | id: string; |
| 1327 | kind: "margin" | "overall" | "leak" | "drift" | "workspace" | string; |
| 1328 | /** The product, or the workspace. */ |
| 1329 | subject: string; |
| 1330 | detail: string; |
| 1331 | since: string; |
| 1332 | openedAt: string; |
| 1333 | emailedAt: string | null; |
| 1334 | }; |
| 1335 | |
| 1336 | /** A change to a price, measured from what Cloudflare charged. */ |
| 1337 | export type PriceProposal = { |
| 1338 | id: string; |
| 1339 | meter: string; |
| 1340 | title: string; |
| 1341 | unit: string; |
| 1342 | currentCostMicros: number; |
| 1343 | proposedCostMicros: number; |
| 1344 | changePercent: number; |
| 1345 | markupPercent: number; |
| 1346 | reason: string; |
| 1347 | source: "keeper" | "reconciler" | string; |
| 1348 | /** Far off the current cost: look before approving. */ |
| 1349 | suspect: boolean; |
| 1350 | status: "open" | "applied" | "approved" | "rejected" | "superseded" | string; |
| 1351 | createdAt: string; |
| 1352 | decidedAt: string | null; |
| 1353 | decidedBy: string | null; |
| 1354 | note: string | null; |
| 1355 | effectiveAt: string | null; |
| 1356 | }; |
| 1357 | |
| 1358 | /** One version of one meter's price; never changed once written. */ |
| 1359 | export type PriceVersion = { |
| 1360 | id: string; |
| 1361 | meter: string; |
| 1362 | version: number; |
| 1363 | costMicros: number; |
| 1364 | markupPercent: number; |
| 1365 | priceMicros: number; |
| 1366 | effectiveAt: string; |
| 1367 | reason: string; |
| 1368 | createdBy: string; |
| 1369 | appliedAt: string | null; |
| 1370 | /** |
| 1371 | * What `costMicros` is: `cost`, what g1t pays for a unit; `rate`, a price |
| 1372 | * g1t sets with no cost behind it (the agent rate), so it is no cost; |
| 1373 | * `weight`, a multiplier in millionths, not money. Absent from older |
| 1374 | * billing: read as `cost`. |
| 1375 | */ |
| 1376 | basis?: "cost" | "rate" | "weight" | ""; |
| 1377 | }; |
| 1378 | |
| 1379 | /** `detachTestStripe`'s arguments. `confirm`: the slug, or "detach" for every workspace; not needed for a dry run. */ |
| 1380 | export type DetachTestStripeArgs = { |
| 1381 | workspace?: string | null; |
| 1382 | exclude?: string[] | null; |
| 1383 | dryRun: boolean; |
| 1384 | cancelAtStripe?: boolean; |
| 1385 | confirm?: string; |
| 1386 | by: string; |
| 1387 | }; |
| 1388 | |
| 1389 | /** One workspace's detach (snake_case, as billing sends it). */ |
| 1390 | export type WorkspaceDetach = { |
| 1391 | workspace: string; |
| 1392 | done: boolean; |
| 1393 | customer: boolean; |
| 1394 | card: string | null; |
| 1395 | card_cached: boolean; |
| 1396 | subscriptions: number; |
| 1397 | card_checks: number; |
| 1398 | checkouts: number; |
| 1399 | ai_reload: boolean; |
| 1400 | autopay_cleared: boolean; |
| 1401 | invoices_voided: number; |
| 1402 | months_skipped: string[]; |
| 1403 | credit_grants_closed: number; |
| 1404 | credit_closed_micros: number; |
| 1405 | payments_reversed_micros: number; |
| 1406 | plan_payments_reversed_micros: number; |
| 1407 | written_off_micros: number; |
| 1408 | balance_before_micros: number; |
| 1409 | balance_after_micros: number; |
| 1410 | stripe_canceled: number; |
| 1411 | stripe_errors: string[]; |
| 1412 | /** Metered figures of months before this one marked charged without a charge, and what they came to. */ |
| 1413 | pending_months_marked: number; |
| 1414 | pending_marked_micros: number; |
| 1415 | /** This month's metered figures kept as the baseline later reports are charged past. */ |
| 1416 | pending_baselined: number; |
| 1417 | pending_baselined_micros: number; |
| 1418 | /** This month's draws on the plan's included usage removed. */ |
| 1419 | plan_credit_cleared_micros: number; |
| 1420 | /** What lost test-mode disputes left owed, cleared. */ |
| 1421 | dispute_owed_cleared_micros: number; |
| 1422 | /** Open test-mode disputes closed. */ |
| 1423 | disputes_closed: number; |
| 1424 | }; |
| 1425 | |
| 1426 | /** What `detachTestStripe` changed, or would change. */ |
| 1427 | export type TestStripeDetach = { |
| 1428 | dry_run: boolean; |
| 1429 | workspaces: WorkspaceDetach[]; |
| 1430 | skipped: { workspace: string; reason: string }[]; |
| 1431 | /** Workspaces left for another call (25 a call). */ |
| 1432 | remaining: number; |
| 1433 | }; |
| 1434 | |
| 1435 | /** What `resetBilling` removed. */ |
| 1436 | export type BillingReset = { workspace: string; rows: number; refreshed?: boolean }; |
| 1437 | |
| 1438 | export type WorkspaceCost = { workspace: string; costMicros: number; revenueMicros: number; givenMicros?: number; internal: boolean }; |
| 1439 | |
| 1440 | export type CostLineSummary = { |
| 1441 | product: string; |
| 1442 | meter: string; |
| 1443 | rawName: string; |
| 1444 | unit: string; |
| 1445 | source: string; |
| 1446 | quantity: number; |
| 1447 | costMicros: number; |
| 1448 | /** Absent when no mapping claims it. */ |
| 1449 | bucket: string | null; |
| 1450 | }; |
| 1451 | |
| 1452 | export type CostMapping = { |
| 1453 | product: string; |
| 1454 | meter: string; |
| 1455 | bucket: string; |
| 1456 | priceMeter: string | null; |
| 1457 | ownMeter: string | null; |
| 1458 | scaleToOwn: boolean; |
| 1459 | driftPercent: number; |
| 1460 | note: string; |
| 1461 | updatedAt: string; |
| 1462 | updatedBy: string; |
| 1463 | }; |
| 1464 | |
| 1465 | export type CostMappingInput = { |
| 1466 | product: string; |
| 1467 | meter: string; |
| 1468 | bucket?: string; |
| 1469 | priceMeter?: string | null; |
| 1470 | ownMeter?: string | null; |
| 1471 | scaleToOwn?: boolean; |
| 1472 | driftPercent?: number | null; |
| 1473 | note?: string; |
| 1474 | remove?: boolean; |
| 1475 | }; |
| 1476 | |
| 1477 | export type CostSettings = { |
| 1478 | autoApply: boolean; |
| 1479 | autoApplyPercent: number; |
| 1480 | noticeDays: number; |
| 1481 | marginFloorPercent: number; |
| 1482 | alertDays: number; |
| 1483 | minDailyCostMicros: number; |
| 1484 | anomalyFactor: number; |
| 1485 | anomalyFloorMicros: number; |
| 1486 | }; |
| 1487 | |
| 1488 | export type CostsReport = { |
| 1489 | configured: boolean; |
| 1490 | fetchedAt: string | null; |
| 1491 | since: string; |
| 1492 | until: string; |
| 1493 | days: CostDay[]; |
| 1494 | products: ProductMargin[]; |
| 1495 | overall: OverallMargin; |
| 1496 | drift: CostDrift[]; |
| 1497 | alerts: MarginAlert[]; |
| 1498 | proposals: PriceProposal[]; |
| 1499 | versions: PriceVersion[]; |
| 1500 | topWorkspaces: WorkspaceCost[]; |
| 1501 | lines: CostLineSummary[]; |
| 1502 | mappings: CostMapping[]; |
| 1503 | settings: CostSettings; |
| 1504 | /** g1t's own spend against its two caps. */ |
| 1505 | caps: SpendCaps; |
| 1506 | /** Cloudflare's current billing cycle: usage cost so far by meter, and the projection. Absent until the bill is read. */ |
| 1507 | cycle?: CloudflareCycle | null; |
| 1508 | /** The last read of Cloudflare's billable usage: what came back. */ |
| 1509 | billRead?: BillRead | null; |
| 1510 | /** Of the range's cost, what no workspace's usage could carry: running g1t, attributed to no one. */ |
| 1511 | unattributedMicros?: number; |
| 1512 | }; |
| 1513 | |
| 1514 | /** Cloudflare's billing cycle, as its Billable usage page shows it. */ |
| 1515 | export type CloudflareCycle = { |
| 1516 | /** First and last days, YYYY-MM-DD, UTC. */ |
| 1517 | start: string; |
| 1518 | end: string; |
| 1519 | days: number; |
| 1520 | /** Days from its start to today, today included. */ |
| 1521 | daysElapsed: number; |
| 1522 | /** Usage cost so far, after the included allowances. */ |
| 1523 | usageMicros: number; |
| 1524 | /** usageMicros over the days elapsed, times the cycle's days. */ |
| 1525 | projectedMicros: number; |
| 1526 | averageDailyMicros: number; |
| 1527 | /** Cloudflare's subscriptions for the cycle (not on the usage bill). */ |
| 1528 | subscriptionsMicros: number; |
| 1529 | meters: CycleMeter[]; |
| 1530 | }; |
| 1531 | |
| 1532 | /** One of Cloudflare's meters over the cycle so far. */ |
| 1533 | export type CycleMeter = { |
| 1534 | product: string; |
| 1535 | meter: string; |
| 1536 | rawName: string; |
| 1537 | unit: string; |
| 1538 | quantity: number; |
| 1539 | /** What the cycle includes; null without a list price. */ |
| 1540 | included: number | null; |
| 1541 | billableQuantity: number; |
| 1542 | costMicros: number; |
| 1543 | /** cloudflare: Cloudflare's own cost; list: the list price past the included amount; none: no list price known. */ |
| 1544 | basis: "cloudflare" | "list" | "none" | string; |
| 1545 | }; |
| 1546 | |
| 1547 | /** What the last read of Cloudflare's billable usage got back. */ |
| 1548 | export type BillRead = { |
| 1549 | readAt: string; |
| 1550 | since: string; |
| 1551 | until: string; |
| 1552 | rows: number; |
| 1553 | pages: number; |
| 1554 | consumedRows: number; |
| 1555 | pricingOnlyRows: number; |
| 1556 | costedRows: number; |
| 1557 | }; |
| 1558 | |
| 1559 | /** One level of the platform pause, as sudo shows it. Snake case, as billing sends it. */ |
| 1560 | export type PauseState = { |
| 1561 | level: PauseLevel; |
| 1562 | paused: boolean; |
| 1563 | note: string | null; |
| 1564 | set_by: string | null; |
| 1565 | set_at: string | null; |
| 1566 | /** Set by billing's usage watcher, not a person. */ |
| 1567 | auto: boolean; |
| 1568 | }; |
| 1569 | |
| 1570 | /** One platform metric over an hour or the month so far. */ |
| 1571 | export type PlatformMetric = { |
| 1572 | metric: string; |
| 1573 | title: string; |
| 1574 | value: number; |
| 1575 | /** Its hourly threshold (`PLATFORM_HOURLY_*`); 0: none. */ |
| 1576 | threshold: number; |
| 1577 | /** The script, queue, database or namespace that counted most. */ |
| 1578 | top_name: string | null; |
| 1579 | top_value: number | null; |
| 1580 | }; |
| 1581 | |
| 1582 | /** A breach billing's usage watcher found. */ |
| 1583 | export type PlatformBreach = { |
| 1584 | id: string; |
| 1585 | metric: string; |
| 1586 | hour: string; |
| 1587 | rule: "threshold" | "spike"; |
| 1588 | value: number; |
| 1589 | threshold: number; |
| 1590 | severe: boolean; |
| 1591 | top_name: string | null; |
| 1592 | detail: string; |
| 1593 | /** Levels it paused. */ |
| 1594 | paused: PauseLevel[]; |
| 1595 | opened_at: string; |
| 1596 | emailed_at: string | null; |
| 1597 | }; |
| 1598 | |
| 1599 | /** Billing's `admin_platform_guard`: the platform pause and usage watcher |
| 1600 | * (docs.g1t.sh/guides/deploy-to-cloudflare/#spend-guardrails). */ |
| 1601 | export type PlatformGuard = { |
| 1602 | levels: PauseState[]; |
| 1603 | /** The last hour read, `YYYY-MM-DDTHH:00:00Z`. */ |
| 1604 | hour: string | null; |
| 1605 | last_hour: PlatformMetric[]; |
| 1606 | month: string; |
| 1607 | month_to_date: PlatformMetric[]; |
| 1608 | breaches: PlatformBreach[]; |
| 1609 | /** Whether billing can read Cloudflare's analytics. */ |
| 1610 | can_read: boolean; |
| 1611 | /** `AUTO_PAUSE`: the levels a severe breach may pause. */ |
| 1612 | auto_pause: PauseLevel[]; |
| 1613 | /** What the latest run could not see: each query that failed, with its error. */ |
| 1614 | blind?: { key: string; dataset: string; error: string }[]; |
| 1615 | /** The latest run found every dataset empty: the wrong account, or a token that cannot see it. */ |
| 1616 | empty?: boolean; |
| 1617 | /** The hour the latest run read. */ |
| 1618 | last_run?: string | null; |
| 1619 | }; |
| 1620 | |
| 1621 | /** What g1t pays for itself, at cost, against its caps (billing's `budget`). */ |
| 1622 | export type SpendCaps = { |
| 1623 | /** Today (UTC), YYYY-MM-DD, and this month, YYYY-MM. */ |
| 1624 | day: string; |
| 1625 | month: string; |
| 1626 | /** What g1t paid for itself today across every workspace. */ |
| 1627 | todayMicros: number; |
| 1628 | /** `PLATFORM_DAILY_SPEND_CAP_MICROS`; 0: no breaker. */ |
| 1629 | dailyCapMicros: number; |
| 1630 | /** New workflows, checks and merge queue runs g1t would pay for are paused. */ |
| 1631 | tripped: boolean; |
| 1632 | trippedAt: string | null; |
| 1633 | liftedBy: string | null; |
| 1634 | liftedAt: string | null; |
| 1635 | liftNote: string | null; |
| 1636 | /** This month so far, by what paid: comped, trial, oss, given, unpaid. */ |
| 1637 | monthBuckets: { bucket: string; title: string; micros: number }[]; |
| 1638 | comped: CompedBudget[]; |
| 1639 | /** Free workspaces' share of reconciled costs this month (git, storage, platform). */ |
| 1640 | freeTierMicros: number; |
| 1641 | /** Cloudflare's subscriptions a month: read from Cloudflare each day, else `CLOUDFLARE_FIXED_MONTHLY_MICROS`, an estimate. */ |
| 1642 | fixedMonthlyMicros: number; |
| 1643 | fixedSource?: "cloudflare" | "estimate" | string; |
| 1644 | fixedReadAt?: string | null; |
| 1645 | /** Each subscription, when read from Cloudflare. */ |
| 1646 | fixedItems?: { name: string; monthlyMicros: number }[]; |
| 1647 | /** Of fixedMonthlyMicros, this calendar month's days so far, each at its billing cycle's daily share. */ |
| 1648 | fixedMonthMicros?: number; |
| 1649 | /** Money in this month, through the last reconciled day. */ |
| 1650 | revenueMicros: number; |
| 1651 | /** |
| 1652 | * Of this month's buckets, what was spent on workspaces whose billing a |
| 1653 | * testing reset later wiped (still g1t's spend; the reconciled figures |
| 1654 | * have it only where the reset kept it), and those workspaces. |
| 1655 | */ |
| 1656 | resetMicros?: number; |
| 1657 | resetWorkspaces?: string[]; |
| 1658 | }; |
| 1659 | |
| 1660 | /** A comped account's monthly budget, at cost. */ |
| 1661 | export type CompedBudget = { |
| 1662 | account: string; |
| 1663 | name: string; |
| 1664 | usedMicros: number; |
| 1665 | /** 0: no budget. */ |
| 1666 | ceilingMicros: number; |
| 1667 | /** `COMPED_MONTHLY_CEILING_MICROS`, not the account's own limit. */ |
| 1668 | defaultCeiling: boolean; |
| 1669 | /** 50, 75, 90, 100, or 0. */ |
| 1670 | level: number; |
| 1671 | }; |
| 1672 | |
| 1673 | export type CostsRun = { lines: number; days: number; proposals: number; alerts: number; problems: string[] }; |
| 1674 | |
| 1675 | /** The product families the Usage page groups meters into, in order. */ |
| 1676 | export const PRODUCTS = [ |
| 1677 | { key: "sandboxes", label: "Sandboxes" }, |
| 1678 | { key: "deployments", label: "Deployments" }, |
| 1679 | { key: "git_storage", label: "Git & storage" }, |
| 1680 | { key: "packages", label: "Packages" }, |
| 1681 | { key: "security", label: "Security & quality" }, |
| 1682 | { key: "search", label: "Search" }, |
| 1683 | { key: "observability", label: "Observability" }, |
| 1684 | ] as const; |
| 1685 | |
| 1686 | export type ProductKey = (typeof PRODUCTS)[number]["key"]; |
| 1687 | |
| 1688 | /** What usage came to over a range, and what paid for it: price − discount − included − credits = charged. */ |
| 1689 | export type UsageTotals = { |
| 1690 | /** Usage at price, pending usage included. */ |
| 1691 | priceMicros: number; |
| 1692 | discountMicros: number; |
| 1693 | /** Paid by the plan's included usage, the trial and g1t's pools. */ |
| 1694 | includedMicros: number; |
| 1695 | /** Paid by credit from g1t, and AI credit bought before g1t stopped selling it. */ |
| 1696 | creditsMicros: number; |
| 1697 | /** Left for the workspace to pay. */ |
| 1698 | chargedMicros: number; |
| 1699 | /** Metered this month, charged when it closes. */ |
| 1700 | pendingMicros: number; |
| 1701 | /** What of `pendingMicros` will be charged at the close, after the discount and what g1t covers; absent from an older billing. */ |
| 1702 | pendingChargedMicros?: number; |
| 1703 | costMicros: number; |
| 1704 | }; |
| 1705 | |
| 1706 | export type UsageDay = { day: string; product: string; micros: number }; |
| 1707 | |
| 1708 | /** One agent's (by handle) or one person's (by username) share of the agent product, at price; an empty key for lines attributed to no one. */ |
| 1709 | |
| 1710 | export type UsageAllowance = { used: number; of: number; unit: string }; |
| 1711 | |
| 1712 | export type ProjectUsage = { project: string; micros: number; quantity: number }; |
| 1713 | |
| 1714 | /** One meter over a range. */ |
| 1715 | export type MeterLine = { |
| 1716 | key: string; |
| 1717 | label: string; |
| 1718 | product: string; |
| 1719 | /** `tokens`, `seconds`, `bytes`, `operations`, `requests` or `entries`. */ |
| 1720 | unit: string; |
| 1721 | quantity: number; |
| 1722 | micros: number; |
| 1723 | pendingMicros?: number; |
| 1724 | /** Every day of the range, oldest first, at price. */ |
| 1725 | daily: number[]; |
| 1726 | allowance?: UsageAllowance | null; |
| 1727 | byProject: ProjectUsage[]; |
| 1728 | /** How the quantity is counted, when that needs saying (the agent rate's token weights). */ |
| 1729 | note?: string | null; |
| 1730 | }; |
| 1731 | |
| 1732 | export type ProductUsage = { key: string; label: string; micros: number; meters: MeterLine[] }; |
| 1733 | |
| 1734 | export type UsageReport = { |
| 1735 | from: string; |
| 1736 | until: string; |
| 1737 | totals: UsageTotals; |
| 1738 | days: UsageDay[]; |
| 1739 | products: ProductUsage[]; |
| 1740 | projects: string[]; |
| 1741 | /** The plan's included usage this month, in micros. */ |
| 1742 | included?: UsageAllowance | null; |
| 1743 | discountPercent?: number | null; |
| 1744 | /** AI credit bought before g1t stopped selling it, left now; kept apart from credit for everything. */ |
| 1745 | aiCreditMicros: number; |
| 1746 | creditMicros: number; |
| 1747 | trialMicros?: number | null; |
| 1748 | plan: PlanKind; |
| 1749 | free: boolean; |
| 1750 | }; |
| 1751 | |
| 1752 | export type PostalAddress = { line1: string; line2: string; city: string; state: string; postalCode: string; country: string }; |
| 1753 | |
| 1754 | export type PaymentMethod = { |
| 1755 | kind: string; |
| 1756 | brand?: string | null; |
| 1757 | last4?: string | null; |
| 1758 | expMonth?: number | null; |
| 1759 | expYear?: number | null; |
| 1760 | }; |
| 1761 | |
| 1762 | export type StripeInvoice = { |
| 1763 | id: string; |
| 1764 | number?: string | null; |
| 1765 | status: string; |
| 1766 | totalCents: number; |
| 1767 | currency: string; |
| 1768 | createdAt: string; |
| 1769 | description?: string | null; |
| 1770 | hostedUrl?: string | null; |
| 1771 | pdfUrl?: string | null; |
| 1772 | }; |
| 1773 | |
| 1774 | export type UpcomingInvoice = { closesAt: string; subscriptionsMicros: number; usageMicros: number; totalMicros: number }; |
| 1775 | |
| 1776 | export type BillingDetails = { |
| 1777 | customer: boolean; |
| 1778 | email: string | null; |
| 1779 | name: string | null; |
| 1780 | address: PostalAddress | null; |
| 1781 | taxIdType: string | null; |
| 1782 | taxId: string | null; |
| 1783 | poNumber: string | null; |
| 1784 | language: string | null; |
| 1785 | paymentMethod: PaymentMethod | null; |
| 1786 | invoices: StripeInvoice[]; |
| 1787 | upcoming: UpcomingInvoice; |
| 1788 | unavailable?: string | null; |
| 1789 | /** Whether Stripe Tax can place the customer from the address; without it nothing is charged. */ |
| 1790 | taxLocation?: boolean; |
| 1791 | /** Set when g1t did not charge for want of a billing address. */ |
| 1792 | taxAddressNeededAt?: string | null; |
| 1793 | /** Stripe's check of the tax ID: pending, verified, unverified or unavailable. */ |
| 1794 | taxIdStatus?: string | null; |
| 1795 | /** none, exempt or reverse, as set at Stripe. */ |
| 1796 | taxExempt?: string | null; |
| 1797 | }; |
| 1798 | |
| 1799 | export type BillingDetailsInput = { |
| 1800 | email?: string; |
| 1801 | name?: string; |
| 1802 | address?: PostalAddress; |
| 1803 | taxIdType?: string; |
| 1804 | taxId?: string; |
| 1805 | poNumber?: string; |
| 1806 | language?: string; |
| 1807 | }; |