@giveitsmaller/contracts 0.82.0 → 0.83.0

package/openapi/api.yaml

@@ -103,7 +103,7 @@ info:
     of truth instead of hardcoding magic numbers. A runtime
     `GET /api/uploads/limits` endpoint for dynamic discovery
     (per-tier / per-environment overrides) is a deferred follow-up.
-  version: 2.217.0
+  version: 2.218.0
   contact:
     name: API Support
 
@@ -1813,13 +1813,31 @@ paths:
               credential) requested an operation outside the anonymous
               allow-list. `operation` names the first such operation.
               A register-wall: signing in is the remedy, not upgrading.
-            - `anonymous_quota_exhausted`: an anonymous caller has used
-              its per-IP workflow allowance for the rolling 24 hours.
-              Also a register-wall.
-
-            Both anonymous walls are checked BEFORE the workflow is
-            built, and neither consumes the caller's anonymous
-            allowance. An authenticated caller never receives either.
+            - `anonymous_quota_exhausted`: this create would cost more
+              credits than the caller's per-IP allowance has left in the
+              rolling 24 hours (`schemas/anonymous-policy.yaml`
+              `allowance`). Also a register-wall. Carries `allowance`,
+              `remaining` and `cost`, and `Retry-After` unless the request
+              costs more than the whole allowance.
+            - `anonymous_limit_exceeded`: an anonymous caller's input
+              exceeds a guest-only limit (today: video duration). Also a
+              register-wall.
+
+            The anonymous walls are checked BEFORE the workflow is
+            built, and none consumes the caller's anonymous
+            allowance. An authenticated caller never receives any.
+          headers:
+            Retry-After:
+              required: false
+              description: |
+                Present only on `anonymous_quota_exhausted`, and only when
+                the request's `cost` fits the `allowance` at all: seconds
+                until enough of the caller's rolling 24 h credit window
+                frees up for it. Delta-seconds (RFC 9110). Signing in
+                remains the immediate remedy.
+              schema:
+                type: integer
+                minimum: 0
           content:
             application/json:
               schema:
@@ -1828,6 +1846,7 @@ paths:
                   - $ref: '#/components/schemas/FeatureTierRestrictedResponse'
                   - $ref: '#/components/schemas/AnonymousOperationNotAllowedResponse'
                   - $ref: '#/components/schemas/AnonymousQuotaExhaustedResponse'
+                  - $ref: '#/components/schemas/AnonymousLimitExceededResponse'
                 discriminator:
                   propertyName: error_type
                   mapping:
@@ -1835,6 +1854,7 @@ paths:
                     feature_tier_restricted: '#/components/schemas/FeatureTierRestrictedResponse'
                     anonymous_operation_not_allowed: '#/components/schemas/AnonymousOperationNotAllowedResponse'
                     anonymous_quota_exhausted: '#/components/schemas/AnonymousQuotaExhaustedResponse'
+                    anonymous_limit_exceeded: '#/components/schemas/AnonymousLimitExceededResponse'
               examples:
                 feature_tier_restricted:
                   summary: Free tier referencing a Pro-tier operation
@@ -1866,6 +1886,21 @@ paths:
                     message: "Sign up to keep compressing."
                     message_key: "error.anonymous_quota_exhausted"
                     locale: "en-GB"
+                    allowance: 30
+                    remaining: 2
+                    cost: 5
+                anonymous_limit_exceeded:
+                  summary: Anonymous caller's video is longer than the guest cap
+                  value:
+                    success: false
+                    error: "ANONYMOUS_LIMIT_EXCEEDED"
+                    error_type: "anonymous_limit_exceeded"
+                    message: "Sign up to process videos longer than a minute."
+                    message_key: "error.anonymous_limit_exceeded"
+                    locale: "en-GB"
+                    limit: "video_duration_seconds"
+                    actual: 95
+                    maximum: 60
         '402':
           description: |
             Credit reservation failed (per ticket
@@ -9773,19 +9808,36 @@ components:
     AnonymousQuotaExhaustedResponse:
       description: |
         403 from `POST /api/workflows` when an ANONYMOUS caller (no
-        credential) has used its per-IP workflow allowance for the
-        rolling 24 hours. A register-wall, distinct from the generic
-        `429`: the remedy is signing in, not waiting.
+        credential) asks for a workflow that would cost more CREDITS than
+        its per-IP allowance has left in the rolling 24 hours
+        (`schemas/anonymous-policy.yaml` `allowance`, priced with the same
+        operation weights as a signed-in caller). The request is refused
+        whole; nothing runs. A register-wall, distinct from the generic
+        `429`: the remedy is signing in.
+
+        The recovery figures are REQUIRED fields of this envelope, not
+        localisation parameters (`ErrorEnvelope.message_params` excludes
+        cost numbers): `allowance`, `remaining` and `cost`, in credits.
+
+        Two cases, told apart by `cost` against `allowance`:
+        - `cost <= allowance`: waiting helps. The response carries
+          `Retry-After`, the seconds until enough of the window frees up.
+        - `cost > allowance`: the request can NEVER fit a guest window
+          (the body is not bounded to the allowance). No `Retry-After`;
+          only signing in, or a smaller request, helps.
 
         Mirrors `compression_api`'s `WorkflowController` register-wall
-        (`JobsErrorCode::AnonymousQuotaExhausted`). The allowance is only
-        consumed by a workflow that is actually created, so a refused
-        request does not use it up.
+        (`JobsErrorCode::AnonymousQuotaExhausted`). Credits are charged
+        only by a workflow that is actually created, and released on
+        failure, so a refused request does not use any up.
       allOf:
         - $ref: '#/components/schemas/ErrorEnvelope'
         - type: object
           required:
             - error_type
+            - allowance
+            - remaining
+            - cost
           properties:
             error:
               enum:
@@ -9795,6 +9847,64 @@ components:
               type: string
               enum:
                 - anonymous_quota_exhausted
+            allowance:
+              type: integer
+              minimum: 0
+              description: Credits per rolling 24 h for this IP (the policy value).
+            remaining:
+              type: integer
+              minimum: 0
+              description: Credits left in the window when the request was refused.
+            cost:
+              type: integer
+              minimum: 1
+              description: |
+                What this request would have charged. When it exceeds
+                `allowance`, the request can never fit and `Retry-After`
+                is absent.
+    AnonymousLimitExceededResponse:
+      description: |
+        403 from `POST /api/workflows` when an ANONYMOUS caller's input
+        exceeds a guest-only limit declared in
+        `schemas/anonymous-policy.yaml`. Today the one such limit is the
+        video duration cap (`video.max_duration_seconds`), measured on the
+        upload probe's duration; the create waits for the probe first. A
+        register-wall: signing in lifts the guest limit (the signed-in
+        caller's ordinary class ceilings then apply). Not a
+        processing-class refusal: no class or tier ceiling is involved.
+      allOf:
+        - $ref: '#/components/schemas/ErrorEnvelope'
+        - type: object
+          required:
+            - error_type
+            - limit
+            - actual
+            - maximum
+          properties:
+            error:
+              enum:
+                - ANONYMOUS_LIMIT_EXCEEDED
+            error_type:
+              description: Discriminator for the 403 oneOf. Always `anonymous_limit_exceeded` for this envelope.
+              type: string
+              enum:
+                - anonymous_limit_exceeded
+            limit:
+              description: |
+                Which guest limit was exceeded. OPEN: a consumer that does
+                not know a value shows the envelope's localised message.
+              type: string
+              x-enum-openness: open
+              enum:
+                - video_duration_seconds
+            actual:
+              type: integer
+              minimum: 0
+              description: The input's value, in the unit `limit` names (seconds, rounded up).
+            maximum:
+              type: integer
+              minimum: 0
+              description: The guest limit, from `schemas/anonymous-policy.yaml`.
     FeatureViolation:
       type: object
       description: |

package/operation-capabilities/operation-capabilities.json

@@ -860,5 +860,5 @@
       "isAnimated": "maybe"
     }
   },
-  "schema_version": "2.217.0"
+  "schema_version": "2.218.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.83.0",
+  "description": "Generated contract types for GISL (Give It Smaller). Generated from compression_contracts spec v2.218.0.",
+  "gislContractsSpec": "v2.218.0",
   "license": "Apache-2.0",
   "homepage": "https://docs.giveitsmaller.com",
   "bugs": {