@giveitsmaller/contracts 0.82.0 → 0.84.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@giveitsmaller/contracts",
-  "version": "0.82.0",
-  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.217.0.",
-  "gislContractsSpec": "v2.217.0",
+  "version": "0.84.0",
+  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.219.0.",
+  "gislContractsSpec": "v2.219.0",
   "license": "Apache-2.0",
   "homepage": "https://docs.giveitsmaller.com",
   "bugs": {
@@ -32,6 +32,7 @@
     "./asyncapi/events.yaml": "./asyncapi/events.yaml",
     "./resolution-bands.yaml": "./resolution-bands.yaml",
     "./anonymous-policy.yaml": "./anonymous-policy.yaml",
+    "./pricing-policy.yaml": "./pricing-policy.yaml",
     "./availability/availability.json": "./availability/availability.json",
     "./accepted-options/accepted-options.json": "./accepted-options/accepted-options.json",
     "./accepted-options/image-output-routes.json": "./accepted-options/image-output-routes.json",
@@ -67,7 +68,8 @@
     "operation-capabilities/operation-capabilities.json",
     "code-builder/code-builder-metadata.json",
     "resolution-bands.yaml",
-    "anonymous-policy.yaml"
+    "anonymous-policy.yaml",
+    "pricing-policy.yaml"
   ],
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist', {recursive: true, force: true})\"",

package/pricing-policy.yaml

@@ -0,0 +1,82 @@
+# Pricing policy — the ONE declaration of how a workflow is charged
+# (card 8Y2fppO9; owner decisions 610(4) 2026-09-26 and 635 2026-09-29).
+#
+# 1.1.0 (card cDZuuyg8, owner decision 645(4) 2026-09-30): an already-optimised
+# compress is not charged (`charge.not_charged`). Additive.
+#
+# Read by: api (pins its billing constants to it: OperationCostCalculator,
+# CreditReservationService, UserTier::overdraftLimit), the frontend's pricing
+# copy, the SDKs, and tests/test_pricing_policy.py (holds the relations below).
+#
+# ⚠️ CONTRACT-FIRST. Two of these rules are AHEAD of api main 2a8dd8d5, and
+# `api_today` under each says what the API does until it ships the change.
+# A consumer reading this file for a PRICE must not assume the new rule is
+# live until api's release notes say so.
+
+schema_version: "1.1.0"
+
+charge:
+  # Owner 610(4)(a) + 635(1): pay only for successful results, PER JOB.
+  # A job that completes is charged; a job that fails (after its retries) is
+  # refunded, as is cancelled work. A multi-job workflow with one failed job
+  # is charged for the jobs that completed.
+  basis: per_completed_job
+  refunded_on: [job_failed, workflow_cancelled]
+  # A workflow paused for insufficient credits has its reservation RELEASED
+  # at the pause and reserved again on resume (so a pause that expires
+  # unresumed owes nothing). api main: CreditReservationService
+  # releaseForPause / ResumeWorkflowCommandHandler.
+  on_pause: released_then_reserved_again_on_resume
+  # Reserved at create for the whole workflow (402 balance_exhausted if the
+  # caller cannot afford it), settled per job as jobs end.
+  reserved_at: workflow_create
+  # A long-form fan-out is settled at what it actually used; the unused
+  # part of its worst-case reservation is refunded.
+  fan_out_settlement: actual_usage
+  # Owner 645(4): an OPERATION that could not make the file smaller and
+  # returned the original is NOT charged; its cost is refunded. The job's
+  # other operations are charged as usual. Per operation, not per job. The
+  # FULL predicate, all of which must hold (a flag alone is not enough: the
+  # metrics object rides on every result):
+  not_charged:
+    - when:
+        operation_type: compress
+        status: completed
+        route: same_format        # resolved: output_format original/absent OR equal to the input format
+        metric: already_optimal   # metrics.already_optimal == true
+  not_charged_api_today: already_optimal_operations_are_charged
+  # api main 2a8dd8d5 refunds the WHOLE reservation when any job fails, so a
+  # partially_failed workflow is charged nothing (OperationResultHandler
+  # releaseReservationOnFailure). Changing to per-job is api's follow-up.
+  api_today: whole_workflow_refund_on_any_job_failure
+
+upload:
+  # Owner 610(4)(b) + 635(2): uploading costs nothing. Larger files cost more
+  # to PROCESS, through the size surcharge below.
+  charged: false
+
+size_surcharge:
+  # Added to each operation's weight. The size is the JOB's input (its
+  # primary upload), applied to every operation of the job, not each
+  # operation's intermediate input (api CreateWorkflowCommandHandler).
+  basis: job_input_bytes
+  # surcharge per operation:
+  #   surcharge = min(max_credits, floor((bytes - free_bytes) / step_bytes))
+  #   for bytes > free_bytes, else 0.
+  # Binary units: 52,428,800 B = 50 MiB (api OperationCostCalculator).
+  free_bytes: 52428800
+  step_bytes: 52428800
+  credits_per_step: 1
+  max_credits: 500
+
+overdraft:
+  # Owner 610(4)(c) + 635(3). The limit is per account and is returned by
+  # GET /api/v2/credits/balance (`overdraft_limit`), which is the source for
+  # any caller; only the Basic value is policy.
+  basic_limit: 0
+  # Overdraft debt is repaid ONE credit for ONE credit from the next monthly
+  # grant, on every paid plan. There is no per-plan multiplier.
+  repayment_ratio: 1
+  # api main already repays 1:1 (CreditAccount); its unused per-plan
+  # multipliers (UserTier::overdraftRate) are deleted in api's follow-up.
+  api_today: repays_1_to_1_unused_per_plan_multiplier_present