@limitry/cli 1.0.0-rc.6 → 1.0.0-rc.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/limitry.mjs CHANGED
@@ -691,6 +691,13 @@ function apiErrorFrom(error, response) {
691
691
  }
692
692
 
693
693
  // node_modules/@limitry/sdk/dist/product/limits.js
694
+ var MAX_COST = 1e9;
695
+ function checkedCost(units) {
696
+ if (!Number.isInteger(units) || units < 0 || units > MAX_COST) {
697
+ throw new RangeError(`held.cost(${units}): the cost must be a whole number from 0 to ${MAX_COST}`);
698
+ }
699
+ return units;
700
+ }
694
701
  var LimitExceeded = class extends Error {
695
702
  reason;
696
703
  /** The limit that refused; null when unavailable or too many holds. */
@@ -699,7 +706,10 @@ var LimitExceeded = class extends Error {
699
706
  decision;
700
707
  constructor(decision) {
701
708
  const reason = decision?.reason?.code ?? "unavailable";
702
- super(reason === "unavailable" ? "Limitry could not be reached and a limit denies when unreachable" : reason === "too_many_reservations" ? "Too many open reservations for this subject" : `Limit ${decision?.reason?.limit ?? ""} exceeded`.trim());
709
+ super(reason === "unavailable" ? "Limitry could not be reached and a limit denies when unreachable" : (
710
+ // The API's own sentence (reason.message), one wording everywhere.
711
+ decision?.reason?.message ?? "Refused"
712
+ ));
703
713
  this.name = "LimitExceeded";
704
714
  this.reason = reason;
705
715
  this.limit = decision?.reason?.limit ?? null;
@@ -841,9 +851,13 @@ function createLimits(client, options = {}) {
841
851
  };
842
852
  const idempotencyKey = crypto.randomUUID();
843
853
  const decision = await check(body, idempotencyKey);
844
- const unmetered = { cost: () => {
845
- }, extend: async () => {
846
- } };
854
+ const unmetered = {
855
+ // Checked even unmetered: the mistake shows whether or not
856
+ // Limitry answered.
857
+ cost: (units) => void checkedCost(units),
858
+ extend: async () => {
859
+ }
860
+ };
847
861
  if (decision === UNREACHABLE || decision === TIMED_OUT) {
848
862
  const unheard = () => decision === TIMED_OUT ? releaseUnheard(body, idempotencyKey) : Promise.resolve();
849
863
  if (failMode(request.subject, request.action) === "closed") {
@@ -864,14 +878,16 @@ function createLimits(client, options = {}) {
864
878
  let used = estimate;
865
879
  const held = {
866
880
  cost(units) {
867
- used = units;
881
+ used = checkedCost(units);
868
882
  },
869
883
  async extend(ttlSeconds) {
870
- await client.POST("/reservations/{reservationId}/extend", {
884
+ const { error, response } = await client.POST("/reservations/{reservationId}/extend", {
871
885
  params: { path: { reservationId: id } },
872
- body: ttlSeconds ? { ttlSeconds } : {},
886
+ body: ttlSeconds === void 0 ? {} : { ttlSeconds },
873
887
  signal: AbortSignal.timeout(timeoutMs)
874
888
  });
889
+ if (error !== void 0)
890
+ throw apiErrorFrom(error, response);
875
891
  }
876
892
  };
877
893
  let result;
@@ -5237,7 +5253,7 @@ var OPERATIONS = [
5237
5253
  "idempotentHint": false
5238
5254
  }
5239
5255
  },
5240
- "description": "Asks whether `subject` may do `action` at `cost`, given every enabled limit that applies, and \u2014 in `consume` mode \u2014 uses it. Always 200 for a decision: read `allowed`; `remaining` shows what is left per limit and `retryAfterSeconds` when to try again. An `Idempotency-Key` header makes a retried check return the same decision without using twice. Its API-key check is cached briefly for speed: a revoked key can keep working here for up to 60 seconds.",
5256
+ "description": "Asks whether `subject` may do `action` at `cost`, given every enabled limit that applies, and \u2014 in `consume` mode \u2014 uses it. Always 200 for a decision, allowed or refused: read `allowed`; `limits` shows what is left on each limit and `retryAfterSeconds` when to try again. An `Idempotency-Key` header makes a retried check return the same decision without using twice. Its API-key check is cached briefly for speed: a revoked key can keep working here for up to 60 seconds.",
5241
5257
  "fields": [
5242
5258
  {
5243
5259
  "name": "subject",
@@ -5342,7 +5358,7 @@ var OPERATIONS = [
5342
5358
  "in": "body",
5343
5359
  "type": "string",
5344
5360
  "required": false,
5345
- "description": "`consume` (default) decides and uses; `preview` decides without using; `reserve` decides and HOLDS `cost` (an estimate) until you commit the actual amount or release it \u2014 see `reservation` in the answer. Only a reservation takes a slot of a `concurrent` limit.",
5361
+ "description": "`consume` (default) decides and uses; `preview` decides without using; `reserve` decides and reserves `cost` (what it will probably use) until you commit the actual amount or release it \u2014 see `reservation` in the answer. Only a reservation takes a slot of a `concurrent` limit.",
5346
5362
  "example": "consume",
5347
5363
  "schema": {
5348
5364
  "type": "string",
@@ -5351,7 +5367,7 @@ var OPERATIONS = [
5351
5367
  "preview",
5352
5368
  "reserve"
5353
5369
  ],
5354
- "description": "`consume` (default) decides and uses; `preview` decides without using; `reserve` decides and HOLDS `cost` (an estimate) until you commit the actual amount or release it \u2014 see `reservation` in the answer. Only a reservation takes a slot of a `concurrent` limit."
5370
+ "description": "`consume` (default) decides and uses; `preview` decides without using; `reserve` decides and reserves `cost` (what it will probably use) until you commit the actual amount or release it \u2014 see `reservation` in the answer. Only a reservation takes a slot of a `concurrent` limit."
5355
5371
  }
5356
5372
  },
5357
5373
  {
@@ -5359,13 +5375,13 @@ var OPERATIONS = [
5359
5375
  "in": "body",
5360
5376
  "type": "number",
5361
5377
  "required": false,
5362
- "description": "With `reserve`: how long the hold lasts before it releases itself. Default 300, at most 3600.",
5378
+ "description": "With `reserve`: how long the reservation lasts before it releases itself. Default 300, at most 3600.",
5363
5379
  "example": 300,
5364
5380
  "schema": {
5365
5381
  "type": "integer",
5366
5382
  "minimum": 1,
5367
5383
  "maximum": 3600,
5368
- "description": "With `reserve`: how long the hold lasts before it releases itself. Default 300, at most 3600."
5384
+ "description": "With `reserve`: how long the reservation lasts before it releases itself. Default 300, at most 3600."
5369
5385
  }
5370
5386
  }
5371
5387
  ],
@@ -5394,14 +5410,14 @@ var OPERATIONS = [
5394
5410
  "idempotentHint": false
5395
5411
  }
5396
5412
  },
5397
- "description": "Stops a limit: checks stop enforcing it within a minute, and it leaves the list. It is archived, not erased \u2014 its usage history and credit grants stay, and `POST /v1/limits/{limitId}/restore` brings it back. Owners and admins only, for a person's token.",
5413
+ "description": "Stops a limit: checks stop enforcing it at once, and it leaves the list. It is archived, not erased \u2014 its usage history and credits stay, and `POST /v1/limits/{limitId}/restore` brings it back. Owners and admins only, for a person's token.",
5398
5414
  "fields": [
5399
5415
  {
5400
5416
  "name": "limitId",
5401
5417
  "in": "path",
5402
5418
  "type": "string",
5403
5419
  "required": true,
5404
- "example": "lim_3f0c\u2026",
5420
+ "example": "lmt_3f0c\u2026",
5405
5421
  "schema": {
5406
5422
  "type": "string"
5407
5423
  }
@@ -5430,64 +5446,68 @@ var OPERATIONS = [
5430
5446
  "idempotentHint": false
5431
5447
  }
5432
5448
  },
5433
- "description": "Limits how much of an action a subject may use per window \u2014 for example 200 cents of `ai-call` a month for every `user`. Checks enforce it from then on. Names are unique among the environment's active limits. Owners and admins only, for a person's token.",
5449
+ "description": "Limits how much a subject may use per window \u2014 for example 200 cents a month for every `user`. Only `subject.kind`, `amount` and `window` are needed: `action` defaults to every action (`*`), `unit` to units, and `name` to the sentence the limit reads as. Checks enforce it from then on. What it counts (subject, action, unit, window, every, start, rolling) is fixed once created. Owners and admins only, for a person's token.",
5434
5450
  "fields": [
5435
5451
  {
5436
5452
  "name": "name",
5437
5453
  "in": "body",
5438
5454
  "type": "string",
5439
- "required": true,
5440
- "description": "A name for the limit, unique among its environment's active limits.",
5455
+ "required": false,
5456
+ "description": `A name, unique among the environment's active limits. Default: the sentence the limit reads as, such as "200 cents per user per month". If a limit already has that name, the answer is 409: give this one a name.`,
5441
5457
  "example": "AI budget",
5442
5458
  "schema": {
5443
5459
  "type": "string",
5444
5460
  "minLength": 1,
5445
5461
  "maxLength": 100,
5446
- "description": "A name for the limit, unique among its environment's active limits."
5462
+ "description": `A name, unique among the environment's active limits. Default: the sentence the limit reads as, such as "200 cents per user per month". If a limit already has that name, the answer is 409: give this one a name.`
5447
5463
  }
5448
5464
  },
5449
5465
  {
5450
- "name": "subjectKind",
5466
+ "name": "subject",
5451
5467
  "in": "body",
5452
- "type": "string",
5468
+ "type": "json",
5453
5469
  "required": true,
5454
- "description": "Your own label for who is checked.",
5455
- "example": "user",
5456
- "schema": {
5457
- "type": "string",
5458
- "minLength": 1,
5459
- "maxLength": 100,
5460
- "description": "Your own label for who is checked."
5461
- }
5462
- },
5463
- {
5464
- "name": "subjectId",
5465
- "in": "body",
5466
- "type": "string",
5467
- "required": false,
5468
- "description": "One subject; omit or null for every subject of the kind. A subject's own limit replaces the kind's limits with the same action and window.",
5470
+ "description": 'Who it applies to: `{"kind": "user"}` for every user, `{"kind": "user", "id": "usr_123"}` for one.',
5471
+ "example": {
5472
+ "kind": "user"
5473
+ },
5469
5474
  "schema": {
5470
- "type": [
5471
- "string",
5472
- "null"
5475
+ "type": "object",
5476
+ "properties": {
5477
+ "kind": {
5478
+ "type": "string",
5479
+ "minLength": 1,
5480
+ "maxLength": 100,
5481
+ "description": "Your own label for who is checked: user, team, apikey \u2026"
5482
+ },
5483
+ "id": {
5484
+ "type": [
5485
+ "string",
5486
+ "null"
5487
+ ],
5488
+ "minLength": 1,
5489
+ "maxLength": 100,
5490
+ "description": "One subject; omit or null for every subject of the kind. A subject's own limit replaces the kind's limits with the same action and window."
5491
+ }
5492
+ },
5493
+ "required": [
5494
+ "kind"
5473
5495
  ],
5474
- "minLength": 1,
5475
- "maxLength": 100,
5476
- "description": "One subject; omit or null for every subject of the kind. A subject's own limit replaces the kind's limits with the same action and window."
5496
+ "description": 'Who it applies to: `{"kind": "user"}` for every user, `{"kind": "user", "id": "usr_123"}` for one.'
5477
5497
  }
5478
5498
  },
5479
5499
  {
5480
5500
  "name": "action",
5481
5501
  "in": "body",
5482
5502
  "type": "string",
5483
- "required": true,
5484
- "description": "The action to limit; `*` for every action.",
5503
+ "required": false,
5504
+ "description": "The action to limit. Default: `*`, every action.",
5485
5505
  "example": "ai-call",
5486
5506
  "schema": {
5487
5507
  "type": "string",
5488
5508
  "minLength": 1,
5489
5509
  "maxLength": 100,
5490
- "description": "The action to limit; `*` for every action."
5510
+ "description": "The action to limit. Default: `*`, every action."
5491
5511
  }
5492
5512
  },
5493
5513
  {
@@ -5509,13 +5529,13 @@ var OPERATIONS = [
5509
5529
  "in": "body",
5510
5530
  "type": "string",
5511
5531
  "required": false,
5512
- "description": "What the amount counts (display only). Default: units.",
5532
+ "description": "What the amount counts, in words. Default: units.",
5513
5533
  "example": "cents",
5514
5534
  "schema": {
5515
5535
  "type": "string",
5516
5536
  "minLength": 1,
5517
5537
  "maxLength": 40,
5518
- "description": "What the amount counts (display only). Default: units."
5538
+ "description": "What the amount counts, in words. Default: units."
5519
5539
  }
5520
5540
  },
5521
5541
  {
@@ -5523,7 +5543,7 @@ var OPERATIONS = [
5523
5543
  "in": "body",
5524
5544
  "type": "string",
5525
5545
  "required": true,
5526
- "description": "`minute`, `hour`, `day`, `week`, `month` or `year`: a period of `every` of them, refilled where `start` says (or rolling: see `rolling`). `total`: a balance that never resets, topped up by grants. `concurrent`: at most `amount` held reservations at once.",
5546
+ "description": "`minute`, `hour`, `day`, `week`, `month` or `year`: a period of `every` of them, reset where `start` says (or rolling: see `rolling`). `total`: a balance that never resets, raised by credits. `concurrent`: at most `amount` open reservations at once.",
5527
5547
  "example": "month",
5528
5548
  "schema": {
5529
5549
  "type": "string",
@@ -5537,7 +5557,7 @@ var OPERATIONS = [
5537
5557
  "total",
5538
5558
  "concurrent"
5539
5559
  ],
5540
- "description": "`minute`, `hour`, `day`, `week`, `month` or `year`: a period of `every` of them, refilled where `start` says (or rolling: see `rolling`). `total`: a balance that never resets, topped up by grants. `concurrent`: at most `amount` held reservations at once."
5560
+ "description": "`minute`, `hour`, `day`, `week`, `month` or `year`: a period of `every` of them, reset where `start` says (or rolling: see `rolling`). `total`: a balance that never resets, raised by credits. `concurrent`: at most `amount` open reservations at once."
5541
5561
  }
5542
5562
  },
5543
5563
  {
@@ -5559,16 +5579,16 @@ var OPERATIONS = [
5559
5579
  "in": "body",
5560
5580
  "type": "string",
5561
5581
  "required": false,
5562
- "description": "Where a period begins. `calendar`: UTC boundaries (midnight, Monday, the 1st, 1 January). `anchor`: from the subject's anchor, its billing date, set with `subjects.update` (its first check until then), so an annual plan can refill monthly from its start day. `first_use`: at the first check after the previous period ended. Default: calendar.",
5582
+ "description": "Where a period begins. `calendar`: UTC boundaries (midnight, Monday, the 1st, 1 January). `billing_date`: from the subject's billing date, set with `subjects.update` (its first check until then), so an annual plan can reset monthly from its start day. `first_use`: at the first check after the previous period ended. Default: calendar.",
5563
5583
  "example": "calendar",
5564
5584
  "schema": {
5565
5585
  "type": "string",
5566
5586
  "enum": [
5567
5587
  "calendar",
5568
- "anchor",
5588
+ "billing_date",
5569
5589
  "first_use"
5570
5590
  ],
5571
- "description": "Where a period begins. `calendar`: UTC boundaries (midnight, Monday, the 1st, 1 January). `anchor`: from the subject's anchor, its billing date, set with `subjects.update` (its first check until then), so an annual plan can refill monthly from its start day. `first_use`: at the first check after the previous period ended. Default: calendar."
5591
+ "description": "Where a period begins. `calendar`: UTC boundaries (midnight, Monday, the 1st, 1 January). `billing_date`: from the subject's billing date, set with `subjects.update` (its first check until then), so an annual plan can reset monthly from its start day. `first_use`: at the first check after the previous period ended. Default: calendar."
5572
5592
  }
5573
5593
  },
5574
5594
  {
@@ -5614,50 +5634,12 @@ var OPERATIONS = [
5614
5634
  "scope": "limits:write"
5615
5635
  },
5616
5636
  {
5617
- "operationId": "limits.get",
5618
- "method": "get",
5619
- "path": "/limits/{limitId}",
5620
- "summary": "Get a limit",
5621
- "cli": {
5622
- "command": "limits get",
5623
- "args": [
5624
- "limitId"
5625
- ],
5626
- "confirm": false
5627
- },
5628
- "mcp": {
5629
- "exposed": true,
5630
- "name": "limits_get",
5631
- "hints": {
5632
- "readOnlyHint": true,
5633
- "destructiveHint": false,
5634
- "idempotentHint": true
5635
- }
5636
- },
5637
- "description": "One limit: who it applies to, the action, amount and window.",
5638
- "fields": [
5639
- {
5640
- "name": "limitId",
5641
- "in": "path",
5642
- "type": "string",
5643
- "required": true,
5644
- "example": "lim_3f0c\u2026",
5645
- "schema": {
5646
- "type": "string"
5647
- }
5648
- }
5649
- ],
5650
- "hasBody": false,
5651
- "workspace": true,
5652
- "scope": "limits:read"
5653
- },
5654
- {
5655
- "operationId": "limits.grants.create",
5637
+ "operationId": "limits.credits.create",
5656
5638
  "method": "post",
5657
- "path": "/limits/{limitId}/grants",
5639
+ "path": "/limits/{limitId}/credits",
5658
5640
  "summary": "Add credits to a balance",
5659
5641
  "cli": {
5660
- "command": "limits grants create",
5642
+ "command": "limits credits create",
5661
5643
  "args": [
5662
5644
  "limitId"
5663
5645
  ],
@@ -5665,16 +5647,16 @@ var OPERATIONS = [
5665
5647
  },
5666
5648
  "mcp": {
5667
5649
  "exposed": false,
5668
- "reason": "Adding credits gives value away; an agent asks a person (limit.grant approval)"
5650
+ "reason": "Adding credits gives value away; an agent asks a person (limit.credit approval)"
5669
5651
  },
5670
- "description": "Adds `amount` to one subject's balance \u2014 a limit whose window is `total`. A negative `amount` takes credits back (a refund, a chargeback) and needs a `note` saying why; the balance may go below zero, and checks are refused until it is topped up. Owners and admins, or a workspace API key; an agent asks a person (the `limit.grant` approval).",
5652
+ "description": "Adds `amount` credits to one subject's balance \u2014 a limit whose window is `total`. A negative `amount` takes credits back (a refund, a chargeback) and needs a `note` saying why; the balance may go below zero, and checks are refused until more credits are added. Owners and admins, or a workspace API key; an agent asks a person (the `limit.credit` approval).",
5671
5653
  "fields": [
5672
5654
  {
5673
5655
  "name": "limitId",
5674
5656
  "in": "path",
5675
5657
  "type": "string",
5676
5658
  "required": true,
5677
- "example": "lim_3f0c\u2026",
5659
+ "example": "lmt_3f0c\u2026",
5678
5660
  "schema": {
5679
5661
  "type": "string"
5680
5662
  }
@@ -5728,7 +5710,7 @@ var OPERATIONS = [
5728
5710
  "type": "string",
5729
5711
  "required": false,
5730
5712
  "description": "Required when `amount` is negative.",
5731
- "example": "October top-up",
5713
+ "example": "October credits",
5732
5714
  "schema": {
5733
5715
  "type": "string",
5734
5716
  "maxLength": 200,
@@ -5741,12 +5723,12 @@ var OPERATIONS = [
5741
5723
  "scope": "limits:write"
5742
5724
  },
5743
5725
  {
5744
- "operationId": "limits.grants.list",
5726
+ "operationId": "limits.credits.list",
5745
5727
  "method": "get",
5746
- "path": "/limits/{limitId}/grants",
5747
- "summary": "List a balance's grants",
5728
+ "path": "/limits/{limitId}/credits",
5729
+ "summary": "List a balance's credits",
5748
5730
  "cli": {
5749
- "command": "limits grants list",
5731
+ "command": "limits credits list",
5750
5732
  "args": [
5751
5733
  "limitId"
5752
5734
  ],
@@ -5754,21 +5736,59 @@ var OPERATIONS = [
5754
5736
  },
5755
5737
  "mcp": {
5756
5738
  "exposed": true,
5757
- "name": "limits_grants_list",
5739
+ "name": "limits_credits_list",
5758
5740
  "hints": {
5759
5741
  "readOnlyHint": true,
5760
5742
  "destructiveHint": false,
5761
5743
  "idempotentHint": true
5762
5744
  }
5763
5745
  },
5764
- "description": "Credits added to subjects' balances for this limit, newest first.",
5746
+ "description": "Credits added to (or taken back from) subjects' balances for this limit, newest first.",
5765
5747
  "fields": [
5766
5748
  {
5767
5749
  "name": "limitId",
5768
5750
  "in": "path",
5769
5751
  "type": "string",
5770
5752
  "required": true,
5771
- "example": "lim_3f0c\u2026",
5753
+ "example": "lmt_3f0c\u2026",
5754
+ "schema": {
5755
+ "type": "string"
5756
+ }
5757
+ }
5758
+ ],
5759
+ "hasBody": false,
5760
+ "workspace": true,
5761
+ "scope": "limits:read"
5762
+ },
5763
+ {
5764
+ "operationId": "limits.get",
5765
+ "method": "get",
5766
+ "path": "/limits/{limitId}",
5767
+ "summary": "Get a limit",
5768
+ "cli": {
5769
+ "command": "limits get",
5770
+ "args": [
5771
+ "limitId"
5772
+ ],
5773
+ "confirm": false
5774
+ },
5775
+ "mcp": {
5776
+ "exposed": true,
5777
+ "name": "limits_get",
5778
+ "hints": {
5779
+ "readOnlyHint": true,
5780
+ "destructiveHint": false,
5781
+ "idempotentHint": true
5782
+ }
5783
+ },
5784
+ "description": "One limit: who it applies to, the action, amount and window.",
5785
+ "fields": [
5786
+ {
5787
+ "name": "limitId",
5788
+ "in": "path",
5789
+ "type": "string",
5790
+ "required": true,
5791
+ "example": "lmt_3f0c\u2026",
5772
5792
  "schema": {
5773
5793
  "type": "string"
5774
5794
  }
@@ -5899,7 +5919,7 @@ var OPERATIONS = [
5899
5919
  "in": "path",
5900
5920
  "type": "string",
5901
5921
  "required": true,
5902
- "example": "lim_3f0c\u2026",
5922
+ "example": "lmt_3f0c\u2026",
5903
5923
  "schema": {
5904
5924
  "type": "string"
5905
5925
  }
@@ -5929,18 +5949,20 @@ var OPERATIONS = [
5929
5949
  "idempotentHint": false
5930
5950
  }
5931
5951
  },
5932
- "description": "Makes the environment's limits match `limits`, by name: creates the missing, changes those that differ (an omitted field means its default) and, with `archiveMissing`, archives active limits the list doesn't name. Running it twice changes nothing the second time. Limitry checks the whole list first, and a problem anywhere changes nothing (400, each problem in `details`); then it writes every change at once. `dryRun` answers the plan without writing. For keeping limits in a file in your repository (`limitry sync`). Owners and admins only, for a person's token.",
5952
+ "description": "Makes the environment's limits match `limits`, by name: creates the missing, changes those that differ (an omitted field means its default) and, with `archiveMissing`, archives active limits the list doesn't name. Running it twice changes nothing the second time. Limitry checks the whole list first, and a problem anywhere changes nothing (400, each problem in `details`); then it writes every change at once. What a limit counts is fixed: a different subject, action, unit or window under an existing name is refused until the entry is renamed. `preview` answers what it would do without writing. For keeping limits in a file in your repository (`limitry sync`). Owners and admins only, for a person's token.",
5933
5953
  "fields": [
5934
5954
  {
5935
5955
  "name": "limits",
5936
5956
  "in": "body",
5937
5957
  "type": "json",
5938
5958
  "required": true,
5939
- "description": "Every limit you want, each described whole: an omitted field is its default, as on create. Names are the key and must be unique in the list. At most 200.",
5959
+ "description": "Every limit you want, each described whole: an omitted field is its default, as on create. Names are the key and must be unique in the list. What a limit counts (subject, action, unit, window, every, start, rolling) is fixed: to change it, rename the entry, which creates a new limit. At most 200.",
5940
5960
  "example": [
5941
5961
  {
5942
5962
  "name": "AI budget",
5943
- "subjectKind": "user",
5963
+ "subject": {
5964
+ "kind": "user"
5965
+ },
5944
5966
  "action": "ai-call",
5945
5967
  "amount": 200,
5946
5968
  "unit": "cents",
@@ -5950,103 +5972,29 @@ var OPERATIONS = [
5950
5972
  "schema": {
5951
5973
  "type": "array",
5952
5974
  "items": {
5953
- "type": "object",
5954
- "properties": {
5955
- "name": {
5956
- "type": "string",
5957
- "minLength": 1,
5958
- "maxLength": 100,
5959
- "description": "A name for the limit, unique among its environment's active limits."
5960
- },
5961
- "subjectKind": {
5962
- "type": "string",
5963
- "minLength": 1,
5964
- "maxLength": 100,
5965
- "description": "Your own label for who is checked."
5966
- },
5967
- "subjectId": {
5968
- "type": [
5969
- "string",
5970
- "null"
5971
- ],
5972
- "minLength": 1,
5973
- "maxLength": 100,
5974
- "description": "One subject; omit or null for every subject of the kind. A subject's own limit replaces the kind's limits with the same action and window."
5975
+ "allOf": [
5976
+ {
5977
+ "$ref": "#/components/schemas/LimitInput"
5975
5978
  },
5976
- "action": {
5977
- "type": "string",
5978
- "minLength": 1,
5979
- "maxLength": 100,
5980
- "description": "The action to limit; `*` for every action."
5981
- },
5982
- "amount": {
5983
- "type": "integer",
5984
- "minimum": 1,
5985
- "maximum": 1e9,
5986
- "description": "How many units each subject may use per window."
5987
- },
5988
- "unit": {
5989
- "type": "string",
5990
- "minLength": 1,
5991
- "maxLength": 40,
5992
- "description": "What the amount counts (display only). Default: units."
5993
- },
5994
- "window": {
5995
- "type": "string",
5996
- "enum": [
5997
- "minute",
5998
- "hour",
5999
- "day",
6000
- "week",
6001
- "month",
6002
- "year",
6003
- "total",
6004
- "concurrent"
6005
- ],
6006
- "description": "`minute`, `hour`, `day`, `week`, `month` or `year`: a period of `every` of them, refilled where `start` says (or rolling: see `rolling`). `total`: a balance that never resets, topped up by grants. `concurrent`: at most `amount` held reservations at once."
6007
- },
6008
- "every": {
6009
- "type": "integer",
6010
- "minimum": 1,
6011
- "maximum": 1e3,
6012
- "description": 'How many `window` units a period lasts: `window: "month", every: 3` is a quarter, `window: "hour", every: 5` five hours. Default: 1.'
6013
- },
6014
- "start": {
6015
- "type": "string",
6016
- "enum": [
6017
- "calendar",
6018
- "anchor",
6019
- "first_use"
6020
- ],
6021
- "description": "Where a period begins. `calendar`: UTC boundaries (midnight, Monday, the 1st, 1 January). `anchor`: from the subject's anchor, its billing date, set with `subjects.update` (its first check until then), so an annual plan can refill monthly from its start day. `first_use`: at the first check after the previous period ended. Default: calendar."
6022
- },
6023
- "rolling": {
6024
- "type": "boolean",
6025
- "description": "Count the last window instead of the calendar one (minute, hour or day only). Default: false."
6026
- },
6027
- "enabled": {
6028
- "type": "boolean",
6029
- "description": "Whether checks enforce it. Default: true."
6030
- },
6031
- "failMode": {
6032
- "type": "string",
6033
- "enum": [
6034
- "open",
6035
- "closed"
6036
- ],
6037
- "description": "What your code should do when Limitry can't be reached: `open` (allow) or `closed` (deny). Default: open."
5979
+ {
5980
+ "type": "object",
5981
+ "properties": {
5982
+ "name": {
5983
+ "type": "string",
5984
+ "minLength": 1,
5985
+ "maxLength": 100,
5986
+ "example": "AI budget",
5987
+ "description": "The limit's name: the key a sync matches on, unique in the list."
5988
+ }
5989
+ },
5990
+ "required": [
5991
+ "name"
5992
+ ]
6038
5993
  }
6039
- },
6040
- "required": [
6041
- "name",
6042
- "subjectKind",
6043
- "action",
6044
- "amount",
6045
- "window"
6046
5994
  ]
6047
5995
  },
6048
5996
  "maxItems": 200,
6049
- "description": "Every limit you want, each described whole: an omitted field is its default, as on create. Names are the key and must be unique in the list. At most 200."
5997
+ "description": "Every limit you want, each described whole: an omitted field is its default, as on create. Names are the key and must be unique in the list. What a limit counts (subject, action, unit, window, every, start, rolling) is fixed: to change it, rename the entry, which creates a new limit. At most 200."
6050
5998
  }
6051
5999
  },
6052
6000
  {
@@ -6061,7 +6009,7 @@ var OPERATIONS = [
6061
6009
  }
6062
6010
  },
6063
6011
  {
6064
- "name": "dryRun",
6012
+ "name": "preview",
6065
6013
  "in": "body",
6066
6014
  "type": "boolean",
6067
6015
  "required": false,
@@ -6097,14 +6045,14 @@ var OPERATIONS = [
6097
6045
  "idempotentHint": false
6098
6046
  }
6099
6047
  },
6100
- "description": "Changes any of a limit's fields; checks use the new rule within a minute. Owners and admins only, for a person's token.",
6048
+ "description": "Changes a limit's name, amount, fail mode or whether it is enabled; checks use the new rule at once. What a limit counts (subject, action, unit, window, every, start, rolling) is fixed: a different value is refused (400) \u2014 create a new limit and archive this one. Owners and admins only, for a person's token.",
6101
6049
  "fields": [
6102
6050
  {
6103
6051
  "name": "limitId",
6104
6052
  "in": "path",
6105
6053
  "type": "string",
6106
6054
  "required": true,
6107
- "example": "lim_3f0c\u2026",
6055
+ "example": "lmt_3f0c\u2026",
6108
6056
  "schema": {
6109
6057
  "type": "string"
6110
6058
  }
@@ -6114,71 +6062,97 @@ var OPERATIONS = [
6114
6062
  "in": "body",
6115
6063
  "type": "string",
6116
6064
  "required": false,
6117
- "description": "A name for the limit, unique among its environment's active limits.",
6065
+ "description": "A new name, unique among the environment's active limits.",
6118
6066
  "example": "AI budget",
6119
6067
  "schema": {
6120
6068
  "type": "string",
6121
6069
  "minLength": 1,
6122
6070
  "maxLength": 100,
6123
- "description": "A name for the limit, unique among its environment's active limits."
6071
+ "description": "A new name, unique among the environment's active limits."
6124
6072
  }
6125
6073
  },
6126
6074
  {
6127
- "name": "subjectKind",
6075
+ "name": "amount",
6128
6076
  "in": "body",
6129
- "type": "string",
6077
+ "type": "number",
6130
6078
  "required": false,
6131
- "description": "Your own label for who is checked.",
6132
- "example": "user",
6079
+ "description": "How many units each subject may use per window.",
6080
+ "example": 300,
6133
6081
  "schema": {
6134
- "type": "string",
6135
- "minLength": 1,
6136
- "maxLength": 100,
6137
- "description": "Your own label for who is checked."
6082
+ "type": "integer",
6083
+ "minimum": 1,
6084
+ "maximum": 1e9,
6085
+ "description": "How many units each subject may use per window."
6138
6086
  }
6139
6087
  },
6140
6088
  {
6141
- "name": "subjectId",
6089
+ "name": "enabled",
6142
6090
  "in": "body",
6143
- "type": "string",
6091
+ "type": "boolean",
6144
6092
  "required": false,
6145
- "description": "One subject; omit or null for every subject of the kind. A subject's own limit replaces the kind's limits with the same action and window.",
6093
+ "description": "Whether checks enforce it.",
6146
6094
  "schema": {
6147
- "type": [
6148
- "string",
6149
- "null"
6150
- ],
6151
- "minLength": 1,
6152
- "maxLength": 100,
6153
- "description": "One subject; omit or null for every subject of the kind. A subject's own limit replaces the kind's limits with the same action and window."
6095
+ "type": "boolean",
6096
+ "description": "Whether checks enforce it."
6154
6097
  }
6155
6098
  },
6156
6099
  {
6157
- "name": "action",
6100
+ "name": "failMode",
6158
6101
  "in": "body",
6159
6102
  "type": "string",
6160
6103
  "required": false,
6161
- "description": "The action to limit; `*` for every action.",
6162
- "example": "ai-call",
6104
+ "description": "What your code should do when Limitry can't be reached: `open` (allow) or `closed` (deny).",
6163
6105
  "schema": {
6164
6106
  "type": "string",
6165
- "minLength": 1,
6166
- "maxLength": 100,
6167
- "description": "The action to limit; `*` for every action."
6107
+ "enum": [
6108
+ "open",
6109
+ "closed"
6110
+ ],
6111
+ "description": "What your code should do when Limitry can't be reached: `open` (allow) or `closed` (deny)."
6168
6112
  }
6169
6113
  },
6170
6114
  {
6171
- "name": "amount",
6115
+ "name": "subject",
6172
6116
  "in": "body",
6173
- "type": "number",
6117
+ "type": "json",
6174
6118
  "required": false,
6175
- "description": "How many units each subject may use per window.",
6176
- "example": 200,
6119
+ "description": "Who it applies to. Fixed once the limit is created: to change it, create a new limit and archive this one.",
6120
+ "example": {
6121
+ "kind": "user"
6122
+ },
6177
6123
  "schema": {
6178
- "type": "integer",
6179
- "minimum": 1,
6180
- "maximum": 1e9,
6181
- "description": "How many units each subject may use per window."
6124
+ "type": "object",
6125
+ "properties": {
6126
+ "kind": {
6127
+ "type": "string",
6128
+ "minLength": 1,
6129
+ "maxLength": 100,
6130
+ "description": "Your own label for who is checked: user, team, apikey \u2026"
6131
+ },
6132
+ "id": {
6133
+ "type": [
6134
+ "string",
6135
+ "null"
6136
+ ],
6137
+ "minLength": 1,
6138
+ "maxLength": 100,
6139
+ "description": "One subject; omit or null for every subject of the kind. A subject's own limit replaces the kind's limits with the same action and window."
6140
+ }
6141
+ },
6142
+ "description": "Who it applies to. Fixed once the limit is created: to change it, create a new limit and archive this one."
6143
+ }
6144
+ },
6145
+ {
6146
+ "name": "action",
6147
+ "in": "body",
6148
+ "type": "string",
6149
+ "required": false,
6150
+ "description": "The action. Fixed once the limit is created: to change it, create a new limit and archive this one.",
6151
+ "schema": {
6152
+ "type": "string",
6153
+ "minLength": 1,
6154
+ "maxLength": 100,
6155
+ "description": "The action. Fixed once the limit is created: to change it, create a new limit and archive this one."
6182
6156
  }
6183
6157
  },
6184
6158
  {
@@ -6186,13 +6160,12 @@ var OPERATIONS = [
6186
6160
  "in": "body",
6187
6161
  "type": "string",
6188
6162
  "required": false,
6189
- "description": "What the amount counts (display only). Default: units.",
6190
- "example": "cents",
6163
+ "description": "What the amount counts. Fixed once the limit is created: to change it, create a new limit and archive this one.",
6191
6164
  "schema": {
6192
6165
  "type": "string",
6193
6166
  "minLength": 1,
6194
6167
  "maxLength": 40,
6195
- "description": "What the amount counts (display only). Default: units."
6168
+ "description": "What the amount counts. Fixed once the limit is created: to change it, create a new limit and archive this one."
6196
6169
  }
6197
6170
  },
6198
6171
  {
@@ -6200,8 +6173,7 @@ var OPERATIONS = [
6200
6173
  "in": "body",
6201
6174
  "type": "string",
6202
6175
  "required": false,
6203
- "description": "`minute`, `hour`, `day`, `week`, `month` or `year`: a period of `every` of them, refilled where `start` says (or rolling: see `rolling`). `total`: a balance that never resets, topped up by grants. `concurrent`: at most `amount` held reservations at once.",
6204
- "example": "month",
6176
+ "description": "The window. Fixed once the limit is created: to change it, create a new limit and archive this one.",
6205
6177
  "schema": {
6206
6178
  "type": "string",
6207
6179
  "enum": [
@@ -6214,7 +6186,7 @@ var OPERATIONS = [
6214
6186
  "total",
6215
6187
  "concurrent"
6216
6188
  ],
6217
- "description": "`minute`, `hour`, `day`, `week`, `month` or `year`: a period of `every` of them, refilled where `start` says (or rolling: see `rolling`). `total`: a balance that never resets, topped up by grants. `concurrent`: at most `amount` held reservations at once."
6189
+ "description": "The window. Fixed once the limit is created: to change it, create a new limit and archive this one."
6218
6190
  }
6219
6191
  },
6220
6192
  {
@@ -6222,13 +6194,12 @@ var OPERATIONS = [
6222
6194
  "in": "body",
6223
6195
  "type": "number",
6224
6196
  "required": false,
6225
- "description": 'How many `window` units a period lasts: `window: "month", every: 3` is a quarter, `window: "hour", every: 5` five hours. Default: 1.',
6226
- "example": 1,
6197
+ "description": "How many windows a period lasts. Fixed once the limit is created: to change it, create a new limit and archive this one.",
6227
6198
  "schema": {
6228
6199
  "type": "integer",
6229
6200
  "minimum": 1,
6230
6201
  "maximum": 1e3,
6231
- "description": 'How many `window` units a period lasts: `window: "month", every: 3` is a quarter, `window: "hour", every: 5` five hours. Default: 1.'
6202
+ "description": "How many windows a period lasts. Fixed once the limit is created: to change it, create a new limit and archive this one."
6232
6203
  }
6233
6204
  },
6234
6205
  {
@@ -6236,16 +6207,15 @@ var OPERATIONS = [
6236
6207
  "in": "body",
6237
6208
  "type": "string",
6238
6209
  "required": false,
6239
- "description": "Where a period begins. `calendar`: UTC boundaries (midnight, Monday, the 1st, 1 January). `anchor`: from the subject's anchor, its billing date, set with `subjects.update` (its first check until then), so an annual plan can refill monthly from its start day. `first_use`: at the first check after the previous period ended. Default: calendar.",
6240
- "example": "calendar",
6210
+ "description": "Where a period begins. Fixed once the limit is created: to change it, create a new limit and archive this one.",
6241
6211
  "schema": {
6242
6212
  "type": "string",
6243
6213
  "enum": [
6244
6214
  "calendar",
6245
- "anchor",
6215
+ "billing_date",
6246
6216
  "first_use"
6247
6217
  ],
6248
- "description": "Where a period begins. `calendar`: UTC boundaries (midnight, Monday, the 1st, 1 January). `anchor`: from the subject's anchor, its billing date, set with `subjects.update` (its first check until then), so an annual plan can refill monthly from its start day. `first_use`: at the first check after the previous period ended. Default: calendar."
6218
+ "description": "Where a period begins. Fixed once the limit is created: to change it, create a new limit and archive this one."
6249
6219
  }
6250
6220
  },
6251
6221
  {
@@ -6253,36 +6223,10 @@ var OPERATIONS = [
6253
6223
  "in": "body",
6254
6224
  "type": "boolean",
6255
6225
  "required": false,
6256
- "description": "Count the last window instead of the calendar one (minute, hour or day only). Default: false.",
6226
+ "description": "Whether it counts the last window. Fixed once the limit is created: to change it, create a new limit and archive this one.",
6257
6227
  "schema": {
6258
6228
  "type": "boolean",
6259
- "description": "Count the last window instead of the calendar one (minute, hour or day only). Default: false."
6260
- }
6261
- },
6262
- {
6263
- "name": "enabled",
6264
- "in": "body",
6265
- "type": "boolean",
6266
- "required": false,
6267
- "description": "Whether checks enforce it. Default: true.",
6268
- "schema": {
6269
- "type": "boolean",
6270
- "description": "Whether checks enforce it. Default: true."
6271
- }
6272
- },
6273
- {
6274
- "name": "failMode",
6275
- "in": "body",
6276
- "type": "string",
6277
- "required": false,
6278
- "description": "What your code should do when Limitry can't be reached: `open` (allow) or `closed` (deny). Default: open.",
6279
- "schema": {
6280
- "type": "string",
6281
- "enum": [
6282
- "open",
6283
- "closed"
6284
- ],
6285
- "description": "What your code should do when Limitry can't be reached: `open` (allow) or `closed` (deny). Default: open."
6229
+ "description": "Whether it counts the last window. Fixed once the limit is created: to change it, create a new limit and archive this one."
6286
6230
  }
6287
6231
  }
6288
6232
  ],
@@ -6311,7 +6255,7 @@ var OPERATIONS = [
6311
6255
  "idempotentHint": false
6312
6256
  }
6313
6257
  },
6314
- "description": "Settles a hold with the ACTUAL amount used (`cost`): less than held gives the rest back at once; more is charged in full \u2014 the work happened. A commit after the hold expired still charges `cost`. Repeating a commit answers the same. Its API-key check is cached briefly for speed: a revoked key can keep working here for up to 60 seconds.",
6258
+ "description": "Commits a reservation with the ACTUAL amount used (`cost`): less than reserved gives the rest back at once; more is charged in full \u2014 the work happened. A commit after the reservation expired still charges `cost`. Repeating a commit answers the same. Its API-key check is cached briefly for speed: a revoked key can keep working here for up to 60 seconds.",
6315
6259
  "fields": [
6316
6260
  {
6317
6261
  "name": "reservationId",
@@ -6361,7 +6305,7 @@ var OPERATIONS = [
6361
6305
  "idempotentHint": false
6362
6306
  }
6363
6307
  },
6364
- "description": "Keeps a hold for longer work: it now expires `ttlSeconds` from now (default 300, at most 3600) \u2014 call it again as a heartbeat. Only a held reservation can be extended. Its API-key check is cached briefly for speed: a revoked key can keep working here for up to 60 seconds.",
6308
+ "description": "Keeps a reservation for longer work: it now expires `ttlSeconds` from now (default 300, at most 3600) \u2014 call it again as a heartbeat. Only an open reservation can be extended. Its API-key check is cached briefly for speed: a revoked key can keep working here for up to 60 seconds.",
6365
6309
  "fields": [
6366
6310
  {
6367
6311
  "name": "reservationId",
@@ -6412,7 +6356,7 @@ var OPERATIONS = [
6412
6356
  "idempotentHint": false
6413
6357
  }
6414
6358
  },
6415
- "description": "Gives the whole hold back \u2014 the work did not happen. Repeating a release answers the same; releasing a committed reservation is refused. Its API-key check is cached briefly for speed: a revoked key can keep working here for up to 60 seconds.",
6359
+ "description": "Gives the whole reservation back \u2014 the work did not happen. Repeating a release answers the same; releasing a committed reservation is refused. Its API-key check is cached briefly for speed: a revoked key can keep working here for up to 60 seconds.",
6416
6360
  "fields": [
6417
6361
  {
6418
6362
  "name": "reservationId",
@@ -6450,7 +6394,7 @@ var OPERATIONS = [
6450
6394
  "idempotentHint": true
6451
6395
  }
6452
6396
  },
6453
- "description": "A subject's anchor: when its `anchor` limits' periods start from. A subject is yours (a user, a team, an agent) and exists once a check names it.",
6397
+ "description": "A subject's billing date: when its `billing_date` limits' periods start from. A subject is yours (a user, a team, an agent) and exists once a check names it.",
6454
6398
  "fields": [
6455
6399
  {
6456
6400
  "name": "subjectKind",
@@ -6503,7 +6447,7 @@ var OPERATIONS = [
6503
6447
  "idempotentHint": false
6504
6448
  }
6505
6449
  },
6506
- "description": "Refills one limit on a subject (`limitId`), or every limit on it (`{}`), at once: for goodwill, a promotion or support. The schedule doesn't move: the next refill is still the usual one. A balance goes back to its amount; a concurrent limit is skipped. Send an Idempotency-Key and a repeat resets once. Owners and admins only, for a person's token.",
6450
+ "description": "Resets one limit on a subject (`limitId`), or every limit on it (`{}`), at once: for goodwill, a promotion or support. The schedule doesn't move: the next reset is still the usual one. A balance goes back to its amount; a concurrent limit is skipped. Send an Idempotency-Key and a repeat resets once. Owners and admins only, for a person's token.",
6507
6451
  "fields": [
6508
6452
  {
6509
6453
  "name": "subjectKind",
@@ -6535,7 +6479,7 @@ var OPERATIONS = [
6535
6479
  "type": "string",
6536
6480
  "required": false,
6537
6481
  "description": "Just this limit. Default: every limit on the subject.",
6538
- "example": "lim_3f0c\u2026",
6482
+ "example": "lmt_3f0c\u2026",
6539
6483
  "schema": {
6540
6484
  "type": "string",
6541
6485
  "description": "Just this limit. Default: every limit on the subject."
@@ -6550,7 +6494,7 @@ var OPERATIONS = [
6550
6494
  "operationId": "subjects.update",
6551
6495
  "method": "patch",
6552
6496
  "path": "/subjects/{subjectKind}/{subjectId}",
6553
- "summary": "Set a subject's anchor",
6497
+ "summary": "Set a subject's billing date",
6554
6498
  "cli": {
6555
6499
  "command": "subjects update",
6556
6500
  "args": [
@@ -6568,7 +6512,7 @@ var OPERATIONS = [
6568
6512
  "idempotentHint": false
6569
6513
  }
6570
6514
  },
6571
- "description": "Sets when a subject's `anchor` limits' periods start from: typically its subscription's start date, from your billing system's webhook, so its allowance refills on its own billing day (monthly for an annual plan, too). Owners and admins only, for a person's token.",
6515
+ "description": "Sets when a subject's `billing_date` limits' periods start from: typically its subscription's start date, from your billing system's webhook, so its allowance resets on its own billing day (monthly for an annual plan, too). Owners and admins only, for a person's token.",
6572
6516
  "fields": [
6573
6517
  {
6574
6518
  "name": "subjectKind",
@@ -6595,7 +6539,7 @@ var OPERATIONS = [
6595
6539
  }
6596
6540
  },
6597
6541
  {
6598
- "name": "anchor",
6542
+ "name": "billingDate",
6599
6543
  "in": "body",
6600
6544
  "type": "string",
6601
6545
  "required": true,
@@ -6631,7 +6575,7 @@ var OPERATIONS = [
6631
6575
  "idempotentHint": true
6632
6576
  }
6633
6577
  },
6634
- "description": "Units used, checks allowed and denied for one limit \u2014 across all subjects, or one (`subjectKind` + `subjectId`) \u2014 per hour or per day (UTC), every bucket in the range included. Up to about a minute behind live checks. Default: the last 30 days, by day.",
6578
+ "description": "Units used, checks allowed and refused for one limit \u2014 across all subjects, or one (`subject`, as `kind:id`) \u2014 per hour or per day (UTC), every bucket in the range included. Up to about a minute behind live checks. Default: the last 30 days, by day.",
6635
6579
  "fields": [
6636
6580
  {
6637
6581
  "name": "limitId",
@@ -6639,34 +6583,24 @@ var OPERATIONS = [
6639
6583
  "type": "string",
6640
6584
  "required": true,
6641
6585
  "description": "The limit.",
6642
- "example": "lim_3f0c\u2026",
6586
+ "example": "lmt_3f0c\u2026",
6643
6587
  "schema": {
6644
6588
  "type": "string",
6645
6589
  "description": "The limit."
6646
6590
  }
6647
6591
  },
6648
6592
  {
6649
- "name": "subjectKind",
6650
- "in": "query",
6651
- "type": "string",
6652
- "required": false,
6653
- "description": "With `subjectId`: one subject's usage, not every subject's.",
6654
- "example": "user",
6655
- "schema": {
6656
- "type": "string",
6657
- "description": "With `subjectId`: one subject's usage, not every subject's."
6658
- }
6659
- },
6660
- {
6661
- "name": "subjectId",
6593
+ "name": "subject",
6662
6594
  "in": "query",
6663
6595
  "type": "string",
6664
6596
  "required": false,
6665
- "description": "With `subjectKind`: one subject's usage.",
6666
- "example": "usr_123",
6597
+ "description": "One subject's usage, not every subject's, as `kind:id`.",
6598
+ "example": "user:usr_123",
6667
6599
  "schema": {
6668
6600
  "type": "string",
6669
- "description": "With `subjectKind`: one subject's usage."
6601
+ "minLength": 3,
6602
+ "maxLength": 301,
6603
+ "description": "One subject's usage, not every subject's, as `kind:id`."
6670
6604
  }
6671
6605
  },
6672
6606
  {
@@ -6735,34 +6669,20 @@ var OPERATIONS = [
6735
6669
  "idempotentHint": true
6736
6670
  }
6737
6671
  },
6738
- "description": "Every enabled limit on one subject \u2014 and on its shared subjects (`shared`, comma-separated `kind:id`, such as `team:team_42`) \u2014 with what is used, what is left and when it resets, exact as of now. For showing an end user where they stand: call it from your server with your key, never from a browser. Not a check: nothing is counted. A subject with no limit here answers an empty `limits` list.",
6672
+ "description": "Every enabled limit on one subject (`subject`, as `kind:id`, such as `user:usr_123`) \u2014 and on its shared subjects (`shared`, comma-separated `kind:id`, such as `team:team_42`) \u2014 with what is used, what is left and when it resets, exact as of now. For showing an end user where they stand: call it from your server with your key, never from a browser. Not a check: nothing is counted. A subject with no limit here answers an empty `limits` list.",
6739
6673
  "fields": [
6740
6674
  {
6741
- "name": "kind",
6742
- "in": "query",
6743
- "type": "string",
6744
- "required": true,
6745
- "description": "The subject's kind, as your checks send it.",
6746
- "example": "user",
6747
- "schema": {
6748
- "type": "string",
6749
- "minLength": 1,
6750
- "maxLength": 100,
6751
- "description": "The subject's kind, as your checks send it."
6752
- }
6753
- },
6754
- {
6755
- "name": "id",
6675
+ "name": "subject",
6756
6676
  "in": "query",
6757
6677
  "type": "string",
6758
6678
  "required": true,
6759
- "description": "The subject's id, as your checks send it.",
6760
- "example": "usr_123",
6679
+ "description": "The subject, as `kind:id`: its kind and id as your checks send them.",
6680
+ "example": "user:usr_123",
6761
6681
  "schema": {
6762
6682
  "type": "string",
6763
- "minLength": 1,
6764
- "maxLength": 200,
6765
- "description": "The subject's id, as your checks send it."
6683
+ "minLength": 3,
6684
+ "maxLength": 301,
6685
+ "description": "The subject, as `kind:id`: its kind and id as your checks send them."
6766
6686
  }
6767
6687
  },
6768
6688
  {
@@ -6801,7 +6721,7 @@ var OPERATIONS = [
6801
6721
  "idempotentHint": true
6802
6722
  }
6803
6723
  },
6804
- "description": "A limit's subjects in its CURRENT window, most used first: units used, what is left, how many checks were denied \u2014 `over` when any were. Up to about a minute behind live checks.",
6724
+ "description": "A limit's subjects in its CURRENT window, most used first: units used, what is left, and how many checks it refused. Up to about a minute behind live checks.",
6805
6725
  "fields": [
6806
6726
  {
6807
6727
  "name": "limitId",
@@ -6809,7 +6729,7 @@ var OPERATIONS = [
6809
6729
  "type": "string",
6810
6730
  "required": true,
6811
6731
  "description": "The limit.",
6812
- "example": "lim_3f0c\u2026",
6732
+ "example": "lmt_3f0c\u2026",
6813
6733
  "schema": {
6814
6734
  "type": "string",
6815
6735
  "description": "The limit."
@@ -7888,11 +7808,60 @@ function print(ctx, data, asJson) {
7888
7808
  ctx.io.stdout(String(data));
7889
7809
  }
7890
7810
 
7811
+ // src/product/check.ts
7812
+ var checkCommand = (program2, ctx) => {
7813
+ program2.command("check").description(`Short for \`${brand.name} checks create\``).argument("<subject>", "who is acting, as kind:id (user:usr_123)").argument("<action>", "what they want to do (ai-call)").option("--cost <n>", "units it would use (default 1)").option(
7814
+ "--shared <kind:id>",
7815
+ "a shared subject it also draws from (a team's pool); repeat for more",
7816
+ (value, previous = []) => [...previous, value]
7817
+ ).option("--workspace <slug>", "act in this workspace for one call").option("--json", "the decision as the API answers it").addHelpText(
7818
+ "after",
7819
+ `
7820
+ Example: ${brand.name} check user:usr_123 ai-call --cost 5
7821
+ A refusal exits 0: it's an answer. Errors exit 1.`
7822
+ ).action(
7823
+ async (subject, action, options) => {
7824
+ const cost = options.cost === void 0 ? void 0 : Number(options.cost);
7825
+ if (cost !== void 0 && !Number.isInteger(cost)) {
7826
+ throw new Error("--cost must be a whole number");
7827
+ }
7828
+ const decision = await ctx.client({ workspace: options.workspace }).checks.create(
7829
+ {
7830
+ subject: parseSubject(subject),
7831
+ action,
7832
+ ...cost !== void 0 ? { cost } : {},
7833
+ ...options.shared?.length ? { shared: options.shared.map(parseSubject) } : {}
7834
+ },
7835
+ { idempotencyKey: crypto.randomUUID() }
7836
+ );
7837
+ ctx.io.stdout(options.json ? json(decision) : answer(decision));
7838
+ }
7839
+ );
7840
+ };
7841
+ function parseSubject(value) {
7842
+ const at = value.indexOf(":");
7843
+ if (at <= 0 || at === value.length - 1) {
7844
+ throw new Error(
7845
+ `"${value}": write a subject as kind:id, e.g. user:usr_123`
7846
+ );
7847
+ }
7848
+ return { kind: value.slice(0, at), id: value.slice(at + 1) };
7849
+ }
7850
+ var left = (r) => `${r.name}: ${r.remaining} ${r.unit} left${r.resetsAt ? `, resets ${r.resetsAt}` : ""}`;
7851
+ function answer(decision) {
7852
+ if (decision.allowed) {
7853
+ return decision.limits.length === 0 ? "Allowed. No limit applies." : `Allowed. ${decision.limits.map(left).join("; ")}`;
7854
+ }
7855
+ return decision.reason?.message ?? "Refused.";
7856
+ }
7857
+
7891
7858
  // src/product/limits-sync.ts
7892
7859
  import { readFileSync as readFileSync4 } from "node:fs";
7893
7860
  import { resolve } from "node:path";
7894
7861
  var limitsSyncCommand = (program2, ctx) => {
7895
- const group = program2.commands.find((c) => c.name() === "limits") ?? program2.command("limits").description("archive, create, get, grants, list, restore, sync, update");
7862
+ const group = program2.commands.find((c) => c.name() === "limits") ?? program2.command("limits").description(
7863
+ "archive, create, credits, get, list, restore, sync, update"
7864
+ );
7896
7865
  syncCommand(
7897
7866
  group.command("sync"),
7898
7867
  ctx,
@@ -7907,27 +7876,21 @@ Shortcut: \`${brand.name} sync\`, the same command.`
7907
7876
  ""
7908
7877
  );
7909
7878
  };
7910
- function clientFor(ctx, workspace2) {
7911
- const token = ctx.settings().token ?? "";
7912
- return ctx.client({
7913
- workspace: token.startsWith("pat_") ? workspace2 : false
7914
- });
7915
- }
7916
7879
  function syncCommand(command, ctx, description, more) {
7917
- command.description(description).argument("[file]", "the file to read", "limitry.json").option("--dry-run", "show what would change, and change nothing").option("--limits <json>", "the limits as a JSON array, instead of a file").option(
7880
+ command.description(description).argument("[file]", "the file to read", "limitry.json").option("--preview", "show what would change, and change nothing").option("--limits <json>", "the limits as a JSON array, instead of a file").option(
7918
7881
  "--archive-missing",
7919
7882
  "archive active limits the file doesn't name (restorable)"
7920
7883
  ).option("--workspace <slug>", "act in this workspace for one call").option("--json", "machine-readable output").addHelpText(
7921
7884
  "after",
7922
- '\nThe file: { "limits": [ { "name": "AI budget", "subjectKind": "user", "action": "ai-call", "amount": 200, "unit": "cents", "window": "month" } ] }\nEach limit is described whole: a field left out is its default, as on `limits create`. Names are the key.' + more
7885
+ '\nThe file: { "limits": [ { "name": "AI budget", "subject": { "kind": "user" }, "action": "ai-call", "amount": 200, "unit": "cents", "window": "month" } ] }\nEach limit is described whole: a field left out is its default, as on `limits create`. Names are the key.\nWhat a limit counts (subject, action, unit, window, every, start, rolling) is fixed: to change it, give the entry a new name.' + more
7923
7886
  ).action(
7924
7887
  async (file, options) => {
7925
7888
  const limits = options.limits === void 0 ? readLimitsFile(file) : parseLimits(options.limits, "--limits");
7926
- const result = await clientFor(ctx, options.workspace).limits.sync(
7889
+ const result = await ctx.client({ workspace: options.workspace }).limits.sync(
7927
7890
  {
7928
7891
  limits,
7929
7892
  archiveMissing: options.archiveMissing ?? false,
7930
- dryRun: options.dryRun ?? false
7893
+ preview: options.preview ?? false
7931
7894
  },
7932
7895
  { idempotencyKey: crypto.randomUUID() }
7933
7896
  );
@@ -7977,7 +7940,7 @@ function parseLimits(text, flag2) {
7977
7940
  }
7978
7941
  var show = (value) => typeof value === "string" ? value : JSON.stringify(value);
7979
7942
  function summary(result) {
7980
- const dry = result.dryRun;
7943
+ const dry = result.preview;
7981
7944
  const lines = [
7982
7945
  ...result.created.map(
7983
7946
  (name) => `${dry ? "Would create" : "Created"}: ${name}`
@@ -7997,64 +7960,10 @@ function summary(result) {
7997
7960
  ];
7998
7961
  }
7999
7962
  if (same2 > 0) lines.push(`Unchanged: ${same2}`);
8000
- if (dry) lines.push("Dry run: nothing was changed.");
7963
+ if (dry) lines.push("Preview: nothing was changed.");
8001
7964
  return lines;
8002
7965
  }
8003
7966
 
8004
- // src/product/check.ts
8005
- var checkCommand = (program2, ctx) => {
8006
- program2.command("check").description(`Short for \`${brand.name} checks create\``).argument("<subject>", "who is acting, as kind:id (user:usr_123)").argument("<action>", "what they want to do (ai-call)").option("--cost <n>", "units it would use (default 1)").option(
8007
- "--shared <kind:id>",
8008
- "a shared subject it also draws from (a team's pool); repeat for more",
8009
- (value, previous = []) => [...previous, value]
8010
- ).option("--workspace <slug>", "act in this workspace for one call").option("--json", "the decision as the API answers it").addHelpText(
8011
- "after",
8012
- `
8013
- Example: ${brand.name} check user:usr_123 ai-call --cost 5
8014
- A refusal exits 0: it's an answer. Errors exit 1.`
8015
- ).action(
8016
- async (subject, action, options) => {
8017
- const cost = options.cost === void 0 ? void 0 : Number(options.cost);
8018
- if (cost !== void 0 && !Number.isInteger(cost)) {
8019
- throw new Error("--cost must be a whole number");
8020
- }
8021
- const decision = await clientFor(ctx, options.workspace).checks.create(
8022
- {
8023
- subject: parseSubject(subject),
8024
- action,
8025
- ...cost !== void 0 ? { cost } : {},
8026
- ...options.shared?.length ? { shared: options.shared.map(parseSubject) } : {}
8027
- },
8028
- { idempotencyKey: crypto.randomUUID() }
8029
- );
8030
- ctx.io.stdout(options.json ? json(decision) : answer(decision));
8031
- }
8032
- );
8033
- };
8034
- function parseSubject(value) {
8035
- const at = value.indexOf(":");
8036
- if (at <= 0 || at === value.length - 1) {
8037
- throw new Error(
8038
- `"${value}": write a subject as kind:id, e.g. user:usr_123`
8039
- );
8040
- }
8041
- return { kind: value.slice(0, at), id: value.slice(at + 1) };
8042
- }
8043
- var left = (r) => `${r.name}: ${r.remaining} ${r.unit} left${r.resetsAt ? `, resets ${r.resetsAt}` : ""}`;
8044
- function answer(decision) {
8045
- if (decision.allowed) {
8046
- return decision.remaining.length === 0 ? "Allowed. No limit applies." : `Allowed. ${decision.remaining.map(left).join("; ")}`;
8047
- }
8048
- const retry = decision.retryAfterSeconds !== null ? ` Try again in ${decision.retryAfterSeconds} s.` : "";
8049
- if (decision.reason?.code === "too_many_reservations") {
8050
- return `Refused: too many open reservations for this subject.${retry}`;
8051
- }
8052
- const limit = decision.remaining.find(
8053
- (r) => r.limit === decision.reason?.limit
8054
- );
8055
- return limit ? `Refused by ${left(limit)}.${retry}` : `Refused: a limit is used up.${retry}`;
8056
- }
8057
-
8058
7967
  // src/product/index.ts
8059
7968
  var productCommands = [limitsSyncCommand, checkCommand];
8060
7969
 
@@ -8072,7 +7981,7 @@ function tokenEnvVar() {
8072
7981
  function build(io) {
8073
7982
  let actedIn = null;
8074
7983
  let sending;
8075
- const program2 = new Command().name(brand.name).description(`${brand.productName} command line`).version("1.0.0-rc.6").addHelpText(
7984
+ const program2 = new Command().name(brand.name).description(`${brand.productName} command line`).version("1.0.0-rc.8").addHelpText(
8076
7985
  "after",
8077
7986
  `
8078
7987
  Token: \`${brand.name} login\` stores it in ~/.config/${brand.name}/; ${tokenEnvVar()} overrides.