@maxceem/agw 0.7.1 → 0.8.0

package/dist/agw.mjs

@@ -6,7 +6,7 @@ var __export = (target, all) => {
 };
 
 // <define:__AGW_MANIFEST__>
-var define_AGW_MANIFEST_default = { version: "0.7.1", wrangler: "4.96.0", upgradeFrom: ["0.7.1", "0.7.0", "0.6.4", "0.6.3", "0.6.2", "0.6.1", "0.6.0", "0.5.2", "0.5.1", "0.5.0", "0.4.0"], release: { url: "https://github.com/maxceem/app-ai-gateway/releases/download/v0.7.1/gateway-0.7.1.tar.gz", sha256: "1b3ac4141c993b30bf1e90404dee7a21785a38b686c3f2562ec7b0c07fd4534d", manifest: "8455d531a2dc7df63af0fcbe1d8a181c3b6c74796e5f5a69cacf7890ca2dc42a" } };
+var define_AGW_MANIFEST_default = { version: "0.8.0", wrangler: "4.96.0", upgradeFrom: ["0.8.0", "0.7.2", "0.7.1", "0.7.0", "0.6.4", "0.6.3", "0.6.2", "0.6.1", "0.6.0", "0.5.2", "0.5.1", "0.5.0", "0.4.0"], release: { url: "https://github.com/maxceem/app-ai-gateway/releases/download/v0.8.0/gateway-0.8.0.tar.gz", sha256: "a9039b1c43d68bf0636e5492a4a2cccfa4b0229e61e790ae414174accc52f9c6", manifest: "eb3280cee275a74cf0ad39a25d20d2a0143be7f3be974f0f5635f4bf8aba0b0e" } };
 
 // src/main.ts
 import { Writable as Writable2 } from "node:stream";
@@ -14841,6 +14841,13 @@ var PROVIDER_DESCRIPTORS = {
     directBaseUrl: "https://api.openai.com/",
     auth: { header: "authorization", scheme: "Bearer " },
     nativeClampStyle: "responses",
+    // Images, which report token usage, embeddings and speech.
+    inferencePaths: [
+      "v1/images/generations",
+      "v1/images/edits",
+      "v1/embeddings",
+      "v1/audio/speech"
+    ],
     probePath: "v1/models",
     examplePath: "v1/responses",
     // OpenAI's chat-completions surface deprecated `max_tokens` in favour of
@@ -14850,6 +14857,9 @@ var PROVIDER_DESCRIPTORS = {
     // The two types whose Responses and transcription request shapes the
     // gateway composes itself for custom endpoints.
     endpointPaths: { responses: "v1/responses", audio_transcription: "v1/audio/transcriptions" },
+    // Every JSON answer reports `usage`: tokens for the GPT transcription
+    // models, `{ type: "duration", seconds }` for whisper-1.
+    transcriptionFormats: { metered: ["json", "verbose_json", "diarized_json"], default: "json" },
     modelAuthor: "OpenAI"
   },
   anthropic: {
@@ -14872,6 +14882,14 @@ var PROVIDER_DESCRIPTORS = {
     directBaseUrl: "https://api.x.ai/",
     auth: { header: "authorization", scheme: "Bearer " },
     nativeClampStyle: "responses",
+    // Images and their edits report their cost like chat does; embeddings and
+    // legacy completions answer in tokens, the latter capped in `max_tokens`.
+    inferencePaths: [
+      "v1/images/generations",
+      "v1/images/edits",
+      "v1/embeddings",
+      { path: "v1/completions", clamp: "chat_completions" }
+    ],
     probePath: "v1/models",
     // Native provider paths: xAI transcribes at `v1/stt`, where OpenAI serves
     // `v1/audio/transcriptions`.
@@ -14888,6 +14906,13 @@ var PROVIDER_DESCRIPTORS = {
     directBaseUrl: "https://generativelanguage.googleapis.com/",
     auth: { header: "x-goog-api-key" },
     nativeClampStyle: "gemini_native",
+    // Embeddings. `generateContent` already carries text, images, speech and
+    // transcription; `batchEmbedContents` is left out because each item may name
+    // a model the one in the URL does not.
+    inferencePaths: [
+      "v1beta/models/{model}:embedContent",
+      "v1/models/{model}:embedContent"
+    ],
     probePath: "v1beta/models",
     // Native Gemini generation requests carry the model in the URL rather than
     // in the JSON body, so there is no example path without a model.
@@ -14899,6 +14924,15 @@ var PROVIDER_DESCRIPTORS = {
     directBaseUrl: "https://api.perplexity.ai/",
     auth: { header: "authorization", scheme: "Bearer " },
     nativeClampStyle: "responses",
+    // The Agent API, its model router's three formats, and embeddings.
+    inferencePaths: [
+      { path: "v1/agent", clamp: "responses" },
+      { path: "router/v1/chat/completions", clamp: "chat_completions" },
+      { path: "router/v1/responses", clamp: "responses" },
+      { path: "router/v1/messages", clamp: "anthropic" },
+      "v1/embeddings",
+      "v1/contextualizedembeddings"
+    ],
     // No `probePath`: Perplexity has no unmetered authenticated endpoint.
     examplePath: "chat/completions",
     modelAuthor: "Perplexity"
@@ -14914,6 +14948,13 @@ var PROVIDER_DESCRIPTORS = {
     directBaseUrl: "https://api.deepseek.com/",
     auth: { header: "authorization", scheme: "Bearer " },
     nativeClampStyle: "chat_completions",
+    // Responses, fill-in-the-middle completions and the Anthropic-format API,
+    // which like its chat path carry no `v1/` prefix of their own.
+    inferencePaths: [
+      { path: "responses", clamp: "responses" },
+      { path: "beta/completions", clamp: "chat_completions" },
+      { path: "anthropic/v1/messages", clamp: "anthropic" }
+    ],
     // DeepSeek's OpenAI base URL carries no `v1` segment.
     probePath: "models",
     examplePath: "chat/completions",
@@ -14926,6 +14967,15 @@ var PROVIDER_DESCRIPTORS = {
     directBaseUrl: "https://api.groq.com/",
     auth: { header: "authorization", scheme: "Bearer " },
     nativeClampStyle: "chat_completions",
+    // Its default `json` answer is the transcript alone; `verbose_json` adds the
+    // duration it bills by, and the same `text` a client reads.
+    transcriptionFormats: {
+      metered: ["verbose_json"],
+      default: "json",
+      upgrades: { json: "verbose_json" }
+    },
+    // Speech; transcriptions are a default style already.
+    inferencePaths: ["openai/v1/audio/speech"],
     // Groq's OpenAI-compatible surface is namespaced under `openai/`.
     probePath: "openai/v1/models",
     examplePath: "openai/v1/chat/completions"
@@ -14935,6 +14985,12 @@ var PROVIDER_DESCRIPTORS = {
     directBaseUrl: "https://api.mistral.ai/",
     auth: { header: "authorization", scheme: "Bearer " },
     nativeClampStyle: "chat_completions",
+    // Embeddings, fill-in-the-middle completions and speech.
+    inferencePaths: [
+      "v1/embeddings",
+      { path: "v1/fim/completions", clamp: "chat_completions" },
+      "v1/audio/speech"
+    ],
     probePath: "v1/models",
     modelAuthor: "Mistral"
   },
@@ -14945,6 +15001,21 @@ var PROVIDER_DESCRIPTORS = {
     directBaseUrl: "https://api.together.ai/",
     auth: { header: "authorization", scheme: "Bearer " },
     nativeClampStyle: "chat_completions",
+    // Its default `json` answer is the transcript alone; `verbose_json` adds the
+    // duration it bills by, and the same `text` a client reads.
+    transcriptionFormats: {
+      metered: ["verbose_json"],
+      default: "json",
+      upgrades: { json: "verbose_json" }
+    },
+    // Legacy completions, images, speech and embeddings. Video is a job whose
+    // result is polled for, so it is not here.
+    inferencePaths: [
+      { path: "v1/completions", clamp: "chat_completions" },
+      "v1/images/generations",
+      "v1/audio/speech",
+      "v1/embeddings"
+    ],
     probePath: "v1/models"
   },
   fireworks: {
@@ -14954,6 +15025,13 @@ var PROVIDER_DESCRIPTORS = {
     directBaseUrl: "https://api.fireworks.ai/",
     auth: { header: "authorization", scheme: "Bearer " },
     nativeClampStyle: "chat_completions",
+    // Every format its inference plane speaks, and embeddings.
+    inferencePaths: [
+      { path: "inference/v1/completions", clamp: "chat_completions" },
+      { path: "inference/v1/messages", clamp: "anthropic" },
+      { path: "inference/v1/responses", clamp: "responses" },
+      "inference/v1/embeddings"
+    ],
     // No `probePath`: its list-models call is `v1/accounts/{account}/models`,
     // and the account id cannot be derived from the key. Nothing under
     // `inference/v1/` is documented as a GET.
@@ -14964,6 +15042,8 @@ var PROVIDER_DESCRIPTORS = {
     directBaseUrl: "https://api.cerebras.ai/",
     auth: { header: "authorization", scheme: "Bearer " },
     nativeClampStyle: "chat_completions",
+    // Legacy completions.
+    inferencePaths: [{ path: "v1/completions", clamp: "chat_completions" }],
     probePath: "v1/models"
   },
   moonshot: {
@@ -14973,6 +15053,8 @@ var PROVIDER_DESCRIPTORS = {
     directBaseUrl: "https://api.moonshot.ai/",
     auth: { header: "authorization", scheme: "Bearer " },
     nativeClampStyle: "chat_completions",
+    // The Anthropic-format API.
+    inferencePaths: [{ path: "anthropic/v1/messages", clamp: "anthropic" }],
     probePath: "v1/models",
     modelAuthor: "Moonshot AI"
   },
@@ -15010,6 +15092,13 @@ var PROVIDER_DESCRIPTORS = {
     directBaseUrl: "https://ark.ap-southeast.bytepluses.com/api/v3/",
     auth: { header: "authorization", scheme: "Bearer " },
     nativeClampStyle: "chat_completions",
+    // Responses, Seedream images and multimodal embeddings, all under the base
+    // URL's own `api/v3/`. Seedance video is a polled job, so it is not here.
+    inferencePaths: [
+      { path: "responses", clamp: "responses" },
+      "images/generations",
+      "embeddings/multimodal"
+    ],
     // No `probePath`: ModelArk publishes no list-models call, and its own SDK
     // has no models resource. It also authenticates before it routes, so every
     // path answers the same 401 and a probe would prove nothing about the key.
@@ -15075,6 +15164,7 @@ var APP_STATUSES = ["active", "disabled"];
 var ISSUER_PROVIDERS = ["firebase", "supabase", "auth0", "clerk", "custom"];
 var ENTITLEMENT_CHECKS = ["revenuecat", "custom"];
 var APP_ATTEST_ENVIRONMENTS = ["production", "development"];
+var APP_ATTEST_VERIFY_ON = ["every_request", "token_exchange"];
 var ENDPOINT_SLUG = /^[a-z0-9-]{1,64}$/;
 var PROVIDER_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
 var HTTP_FIELD_NAME = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
@@ -15225,7 +15315,20 @@ var AppleAppAttestAuthenticationSchema = external_exports.object({
      */
     environments: external_exports.array(external_exports.enum(APP_ATTEST_ENVIRONMENTS)).min(1, { error: "environments must name at least one environment" }).refine((values) => new Set(values).size === values.length, {
       error: "environments cannot repeat a value"
-    }).prefault(["production"])
+    }).prefault(["production"]),
+    /**
+     * Where the install's App Attest key proves itself. `every_request`, the
+     * default, binds every gateway request to the device: each one carries
+     * an assertion over that very request, so a copied token is worthless.
+     * `token_exchange` checks the assertion only when the hourly gateway
+     * token is minted, and requests then carry the token alone; limits and
+     * budgets still count per install, because the token names it.
+     */
+    verify_on: external_exports.enum(APP_ATTEST_VERIFY_ON, {
+      error: "verify_on must be one of every_request, token_exchange"
+    }).default("every_request").meta({
+      description: "When the install's App Attest assertion is verified. every_request (the default): every gateway request carries X-AppAttest-Proof, a fresh assertion over that request; needs the AppAIGateway Swift package 1.4 or later. token_exchange: the assertion is verified once, when the hourly gateway token is exchanged, and requests carry only the token."
+    })
   }).strict()
 }).strict();
 var ApiKeyAuthenticationSchema = external_exports.object({
@@ -15268,6 +15371,14 @@ var LimitScopeSchema = external_exports.object({
   }).strict(),
   spending: external_exports.object({ monthly_usd: NullableSpendLimit }).strict()
 }).strict();
+var BUDGET_SCOPES = ["install", "user"];
+var PerUserLimitScopeSchema = LimitScopeSchema.extend({
+  spending: LimitScopeSchema.shape.spending.extend({
+    scope: external_exports.enum(BUDGET_SCOPES).optional().meta({
+      description: "Whose month monthly_usd is measured over: install (the default on App Attest applications) or user (the default, and the only value, on server applications). user on an App Attest application needs authentication.end_user.source issuer. Filled in on every parsed configuration."
+    })
+  }).strict()
+}).strict();
 var UNLIMITED_SCOPE = {
   requests: { per_minute: null, per_day: null },
   spending: { monthly_usd: null }
@@ -15306,7 +15417,7 @@ var AppConfigSchema = external_exports.object({
    * parsed configuration: an unwritten block is the unlimited one.
    */
   limits: external_exports.object({
-    per_user: LimitScopeSchema.prefault(UNLIMITED_SCOPE),
+    per_user: PerUserLimitScopeSchema.prefault(UNLIMITED_SCOPE),
     per_app: LimitScopeSchema.prefault(UNLIMITED_SCOPE)
   }).strict().prefault({}),
   endpoints: external_exports.record(
@@ -15324,6 +15435,29 @@ var AppConfigSchema = external_exports.object({
       message: "needs an authentication.end_user source other than none: this application identifies no end users, so use limits.per_app"
     });
   }
+  const budgetScope = perUser?.spending.scope;
+  if (authentication !== void 0 && budgetScope !== void 0) {
+    if (authentication.type === "api_key" && budgetScope === "install") {
+      context.addIssue({
+        code: "custom",
+        path: ["limits", "per_user", "spending", "scope"],
+        message: "cannot be install: server applications have no install; the budget is per user"
+      });
+    }
+    if (authentication.type === "apple_app_attest" && budgetScope === "user" && authentication.end_user.source !== "issuer") {
+      context.addIssue({
+        code: "custom",
+        path: ["limits", "per_user", "spending", "scope"],
+        message: "can be user only when authentication.end_user.source is issuer: under app_install every install is its own user, so use install"
+      });
+    }
+  }
+}).overwrite((config2) => {
+  const spending = config2.limits.per_user.spending;
+  if (spending.scope === void 0) {
+    spending.scope = config2.authentication.type === "apple_app_attest" ? "install" : "user";
+  }
+  return config2;
 }).meta({ id: "AppConfig" });
 var APP_ID_IS_SERVER_ASSIGNED = "id is assigned by the server: omit it and read app.id from the response";
 var AppWriteSchema = external_exports.object({
@@ -15760,13 +15894,13 @@ var commands = {
   "provider-gateway remove": { args: 1, flags: "yes!" },
   "app add": {
     args: 0,
-    flags: "type name team-id bundle-id attest-environments provider* status file key-output dry-run!"
+    flags: "type name team-id bundle-id attest-environments verify-on provider* status file key-output dry-run!"
   },
   "app list": { args: 0, flags: "" },
   "app show": { args: 1, flags: "" },
   "app update": {
     args: 1,
-    flags: "name team-id bundle-id attest-environments provider* all-providers! status file dry-run!"
+    flags: "name team-id bundle-id attest-environments verify-on provider* all-providers! status file dry-run!"
   },
   "app validate": { args: 0, flags: "file" },
   "app check": { args: 1, flags: "" },
@@ -16706,6 +16840,12 @@ var StateStore = class {
 function selectedProviderPolicies(routing) {
   return routing.providers.mode === "selected" ? routing.providers.selected : {};
 }
+var DEFAULT_INFERENCE_PATHS = new Map(
+  PROVIDER_TYPES.map((type) => [
+    type,
+    (providerDescriptor(type).inferencePaths ?? []).map((entry) => typeof entry === "string" ? { path: entry, clamp: "none" } : { ...entry })
+  ])
+);
 
 // ../src/shared/protocols.ts
 var PROTOCOLS = {
@@ -16844,7 +16984,7 @@ async function appDocument(flags, current) {
     if (!["ios", "server"].includes(type))
       fail("invalid_input", "App type must be ios or server.");
     const ios = type === "ios";
-    if (!ios && ["team-id", "bundle-id", "attest-environments"].some((k) => flags[k]))
+    if (!ios && IOS_FLAGS.some((k) => flags[k]))
       fail("invalid_input", "Server apps cannot use iOS flags.");
     const bundle = ios ? await required2(flags, "bundle-id", "Apple bundle ID") : null;
     doc = localApp({
@@ -16871,7 +17011,7 @@ async function appDocument(flags, current) {
   if (flags.name) doc.name = flags.name;
   if (flags.status) doc.status = flags.status === "disabled" ? "disabled" : "active";
   const auth = doc.config.authentication;
-  if (auth.type === "api_key" && ["team-id", "bundle-id", "attest-environments"].some((k) => flags[k]))
+  if (auth.type === "api_key" && IOS_FLAGS.some((k) => flags[k]))
     fail("invalid_input", "Server apps cannot use iOS flags.");
   if (auth.type === "apple_app_attest") {
     if (flags["key-output"])
@@ -16880,6 +17020,8 @@ async function appDocument(flags, current) {
     if (flags["bundle-id"]) auth.app_attest.bundle_id = flags["bundle-id"];
     if (flags["attest-environments"])
       auth.app_attest.environments = attestEnvironments(flags["attest-environments"]);
+    if (flags["verify-on"])
+      auth.app_attest.verify_on = flags["verify-on"].trim();
   }
   const selectedProviders = flagList(flags.provider);
   if (selectedProviders.length) {
@@ -16894,6 +17036,7 @@ async function appDocument(flags, current) {
   if (flags["all-providers"]) doc.config.routing.providers = { mode: "all" };
   return localApp(doc);
 }
+var IOS_FLAGS = ["team-id", "bundle-id", "attest-environments", "verify-on"];
 function attestEnvironments(value) {
   return value.split(",").map((name) => name.trim()).filter((name) => name.length > 0);
 }
@@ -16979,7 +17122,7 @@ ${snippet}`;
         ...snippet ? { snippet } : {},
         app: app2,
         ...key ? { applicationKey: key } : {},
-        guidance: doc.config.authentication.type === "apple_app_attest" ? `Add https://github.com/maxceem/app-ai-gateway-swift from 1.0.0, enable App Attest, and test on a supported physical device. Run agw app snippet ${app2.id} --provider <slug> for integration code. Production releases should use production-only App Attest.` : `Store the generated key on your server; never embed it in a mobile application. Run agw app snippet ${app2.id} for this request again.`
+        guidance: doc.config.authentication.type === "apple_app_attest" ? `Add https://github.com/maxceem/app-ai-gateway-swift from 1.4.0, enable App Attest, and test on a supported physical device. Run agw app snippet ${app2.id} --provider <slug> for integration code. Production releases should use production-only App Attest.` : `Store the generated key on your server; never embed it in a mobile application. Run agw app snippet ${app2.id} for this request again.`
       };
     }
   }
@@ -17078,9 +17221,11 @@ var REJECTION_REASONS = [
   "blocked_app_rate",
   "blocked_app_budget",
   "blocked_billing",
-  "blocked_user"
+  "blocked_user",
+  /** An App Attest assertion whose counter the install had already used. */
+  "blocked_replay"
 ];
-var REJECTION_SCOPES = ["user", "app", "account"];
+var REJECTION_SCOPES = ["user", "install", "app", "account"];
 
 // ../src/contracts/billing.ts
 var BillingSubscriptionStatusSchema = external_exports.enum([
@@ -17231,6 +17376,7 @@ var USAGE_BREAKDOWN_DIMENSIONS = [
   "credential_source",
   "model_author",
   "user",
+  "install",
   "status",
   "cost_source",
   "route",
@@ -17242,7 +17388,7 @@ var ErrorResponseSchema = external_exports.object({
     code: external_exports.string(),
     message: external_exports.string(),
     data: external_exports.record(external_exports.string(), external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean()])).optional().meta({
-      description: "Machine-readable facts about this rejection, present only where the code alone is not actionable. A billing_request_quota_exceeded rejection carries periodId, periodStart, periodEnd, limit, used, and resetAt; a billing_plan_limit_reached rejection carries limit and used; an app_rate_limited or app_budget_exhausted rejection carries scope, either user or app; a rate_limited rejection carries scope naming the endpoint policy that refused, plus limit, windowSeconds, retryAfterSeconds and resetAt."
+      description: "Machine-readable facts about this rejection, present only where the code alone is not actionable. A billing_request_quota_exceeded rejection carries periodId, periodStart, periodEnd, limit, used, and resetAt; a billing_plan_limit_reached rejection carries limit and used; an app_rate_limited or app_budget_exhausted rejection carries scope, one of user, install or app; a rate_limited rejection carries scope naming the endpoint policy that refused, plus limit, windowSeconds, retryAfterSeconds and resetAt."
     })
   })
 }).meta({ id: "ErrorResponse" });
@@ -17272,17 +17418,23 @@ var AppAttestChallengeResponseSchema = external_exports.object({
 var AppAttestRegisterResponseSchema = external_exports.object({ user_id: external_exports.string() });
 var GatewayTokenResponseSchema = external_exports.object({
   access_token: external_exports.string(),
-  expires_in: external_exports.number()
+  expires_in: external_exports.number(),
+  verify_on: external_exports.enum(APP_ATTEST_VERIFY_ON).optional().meta({
+    description: "On App Attest applications, when the gateway verifies the install's assertion: every_request means every request sent with this token must carry X-AppAttest-Proof; token_exchange means requests carry only the token. Absent on other applications."
+  })
 });
 var CurrentUserResponseSchema = external_exports.object({
   user_id: external_exports.string(),
+  install_id: external_exports.string().nullable().meta({
+    description: "The App Attest key id of the install making the request, on App Attest applications, whose request limits are counted per install. Null on server applications."
+  }),
   limits: external_exports.object({
-    requests_today: external_exports.number().int().nullable().meta({ description: "Requests this user has made so far in the current UTC day. Null when the application sets no per-user limit, in which case requests are not counted at all." }),
+    requests_today: external_exports.number().int().nullable().meta({ description: "Requests made so far in the current UTC day: by this install on an App Attest application, by this user on a server application. Null when the application sets no per-user limit, in which case requests are not counted at all." }),
     requests_remaining: external_exports.number().int().nullable().meta({ description: "What is left of requests_per_day. Null when no daily limit is set." }),
-    requests_per_minute: external_exports.number().nullable().meta({ description: "The per-user per-minute limit this app sets. Null means unlimited." }),
-    requests_per_day: external_exports.number().nullable().meta({ description: "The per-user per-day limit this app sets. Null means unlimited." }),
-    monthly_cost_usd: external_exports.number().meta({ description: "What this user's traffic has cost so far in the current UTC calendar month." }),
-    monthly_budget_usd: external_exports.number().nullable().meta({ description: "The per-user monthly spending budget this app sets. Null means unlimited." }),
+    requests_per_minute: external_exports.number().nullable().meta({ description: "The per-minute limit this app sets on each install (App Attest) or user (server). Null means unlimited." }),
+    requests_per_day: external_exports.number().nullable().meta({ description: "The per-day limit this app sets on each install (App Attest) or user (server). Null means unlimited." }),
+    monthly_cost_usd: external_exports.number().meta({ description: "What has been spent so far in the current UTC calendar month against the budget below: by this install, or by this user when the budget's scope is user." }),
+    monthly_budget_usd: external_exports.number().nullable().meta({ description: "The monthly spending budget this app sets on each install or user, per limits.per_user.spending.scope. Null means unlimited." }),
     blocked: external_exports.boolean().meta({ description: "Whether this user has been blocked in the console." })
   }).meta({
     description: "The limits the app sets on this user, and where the user stands against them. The account's request allowance is not reported here: it is shared by all apps, and is reported on the rejection that spends it."
@@ -17292,6 +17444,9 @@ var UsageEventSchema = external_exports.object({
   id: external_exports.number().int(),
   /** Null for an application that identifies no end users. */
   user_id: external_exports.string().nullable(),
+  install_id: external_exports.string().nullable().meta({
+    description: "The App Attest key id of the install that made the request, on App Attest applications; null for server applications."
+  }),
   api_key_id: external_exports.string().nullable().meta({
     description: "Non-secret ID of the application API key that authenticated the request, including the client-proof key carried by an exchanged gateway token."
   }),
@@ -17373,6 +17528,9 @@ var AuthEventListSchema = external_exports.object({
 var RejectionEventSchema = external_exports.object({
   id: external_exports.number().int(),
   user_id: external_exports.string().nullable(),
+  install_id: external_exports.string().nullable().meta({
+    description: "The App Attest key id of the refused install, on App Attest applications; null for server applications and for samples recorded before installs were."
+  }),
   api_key_id: external_exports.string().nullable(),
   reason: external_exports.enum(REJECTION_REASONS),
   scope: external_exports.enum(REJECTION_SCOPES).nullable().meta({ description: "Null on historical samples whose limit scope cannot be recovered." }),
@@ -17431,6 +17589,12 @@ var AuthEventSummarySchema = external_exports.object({
     description: "Users currently inside an unclosed claim-propagation window \u2014 stuck mid-activation right now."
   })
 }).meta({ id: "AuthEventSummary" });
+var AppWarningSchema = external_exports.object({
+  code: external_exports.string().meta({ description: "Stable identifier of what the warning is about." }),
+  message: external_exports.string().meta({ description: "What will stop, when, and what to do about it, in one sentence or two." }),
+  until: external_exports.string().optional().meta({ description: "ISO 8601 UTC instant the behaviour stops." }),
+  docs_url: external_exports.string().optional().meta({ description: "Where the change is described." })
+}).meta({ id: "AppWarning" });
 var AppResponseSchema = external_exports.object({
   app: external_exports.object({
     revision: external_exports.number().int().positive(),
@@ -17444,7 +17608,10 @@ var AppResponseSchema = external_exports.object({
     config: AppConfigSchema,
     status: external_exports.enum(APP_STATUSES),
     created_at: external_exports.string(),
-    updated_at: external_exports.string()
+    updated_at: external_exports.string(),
+    warnings: external_exports.array(AppWarningSchema).meta({
+      description: "Behaviour of this application that will stop on a stated date, computed when the application is read; empty when there is none. Read-only: tell the person who owns the app, and act before each date."
+    })
   })
 }).meta({ id: "AppResponse" });
 var AppDeleteResponseSchema = external_exports.object({
@@ -17775,6 +17942,9 @@ var AppCheckResponseSchema = external_exports.object({
   }),
   limitations: external_exports.array(external_exports.string()).meta({
     description: "What this check did not exercise, one sentence each."
+  }),
+  warnings: external_exports.array(AppWarningSchema).meta({
+    description: "The application's warnings, as reading it returns them: behaviour that will stop on a stated date. They never make an application not ready."
   })
 });
 var AppSnippetResponseSchema = external_exports.object({
@@ -17817,9 +17987,16 @@ var ApiKeyRevokeResponseSchema = external_exports.object({
 var GatewayUserSchema = external_exports.object({
   id: external_exports.string(),
   status: external_exports.enum(["active", "blocked"]),
-  attest_key_id: external_exports.string().nullable(),
-  attest_registered: external_exports.boolean(),
-  attest_counter: external_exports.number(),
+  attest_key_id: external_exports.string().nullable().meta({
+    description: "The user's most recently seen App Attest key id, if they hold any. Under app_install it is the user's own id."
+  }),
+  attest_registered: external_exports.boolean().meta({ description: "Whether the user holds at least one App Attest key." }),
+  installs: external_exports.number().int().meta({
+    description: "How many App Attest keys the user holds: one per install, that is one copy of the app on one device, and a new one each time the app is reinstalled. Always 0 on server applications."
+  }),
+  is_install: external_exports.boolean().meta({
+    description: "Whether this row's id is itself a registered App Attest key, so the row is one install: every row of an app_install application, and none of a signed-in user's. Decided per row, so history kept from before an application changed its user identity reads as what it was. A per-install budget measures a row's spend only when this is true."
+  }),
   created_at: external_exports.string(),
   last_seen_at: external_exports.string().nullable(),
   is_virtual: external_exports.boolean(),
@@ -17923,7 +18100,8 @@ var PricesResponseSchema = external_exports.object({
 var OperationResultSchema = external_exports.object({
   /** The account a claim settled, a login landed in, or a bootstrap created. */
   accountId: external_exports.string().optional(),
-  app: AppResponseSchema.shape.app.optional(),
+  // An outcome recorded before warnings existed has none.
+  app: AppResponseSchema.shape.app.extend({ warnings: AppResponseSchema.shape.app.shape.warnings.optional() }).optional(),
   api_key: AppKeyMetadataSchema.nullable().optional(),
   provider: ProviderSummarySchema.optional(),
   gateway: ProviderGatewaySummarySchema.optional()
@@ -17950,7 +18128,7 @@ var RevealedOperationResponseSchema = external_exports.object({
   id: external_exports.string(),
   kind: external_exports.string(),
   result: external_exports.object({
-    app: AppResponseSchema.shape.app.optional(),
+    app: AppResponseSchema.shape.app.extend({ warnings: AppResponseSchema.shape.app.shape.warnings.optional() }).optional(),
     /** `key` is the plaintext. It is shown this once; the gateway keeps only a hash. */
     api_key: CreatedApiKeySchema.nullable().optional()
   })
@@ -18271,6 +18449,9 @@ var GatewayClientHeadersSchema = external_exports.object({
   "x-app-version": external_exports.string().optional().meta({
     description: "Required for gateway-token clients; optional for issuer-less API-key clients."
   }),
+  "x-appattest-proof": external_exports.string().regex(/^v1\.[0-9]{1,12}\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]+$/).optional().meta({
+    description: "Required on every request sent with the gateway token of an App Attest application whose authentication.app_attest.verify_on is every_request; ignored, and never forwarded, where verify_on is token_exchange and for API-key clients. Format `v1.<timestamp>.<nonce>.<assertion>`: decimal unix seconds from the device clock (signed, but not compared with the gateway's clock), 16 random bytes as base64url without padding, and the CBOR assertion from DCAppAttestService.generateAssertion as base64url without padding. The assertion's client data is the SHA-256 of these lines joined by \\n with no trailing newline: `appaigateway-request-v1`, the app id, the upper-case HTTP method, the URL path and query exactly as sent, base64url(sha256(body bytes)) (an absent body hashes as empty), base64url(sha256(the bearer token)), the timestamp, and the nonce. Missing answers 401 assertion_required; refused answers 403 attest_failed. The AppAIGateway Swift package 1.4 or later computes it."
+  }),
   "x-end-user-id": external_exports.string().optional().meta({
     description: "Optional configured end-user identity for issuer-less API-key applications."
   })
@@ -18391,7 +18572,7 @@ var CATALOG = {
     path: "/v1/apps/{app}/auth/token",
     tags: ["Application authentication"],
     summary: "Exchange issuer identity and client proof for a gateway token",
-    description: "App Attest clients send key_id, assertion, and challenge. Issuer-backed API-key clients send api_key and issuer_token. The verified issuer claim is always the resulting user identity.",
+    description: "App Attest clients send key_id, assertion, and challenge; the assertion is verified here whatever the application's verify_on, and the answer's verify_on says whether requests sent with the token must also carry X-AppAttest-Proof. Issuer-backed API-key clients send api_key and issuer_token. The verified issuer claim is always the resulting user identity.",
     security: "public",
     params: APP_PARAM,
     request: external_exports.union([AppAttestTokenRequestSchema, ApiKeyTokenRequestSchema]),
@@ -18404,8 +18585,10 @@ var CATALOG = {
     path: "/v1/apps/{app}/me",
     tags: ["Application"],
     summary: "Get the current user's limits, spend and block state",
+    description: "On an App Attest application the request limits and, by default, the budget are the install's; install_id names it. Signed with X-AppAttest-Proof like every other request where the application verifies App Attest on every request.",
     security: "gateway",
     params: APP_PARAM,
+    headers: GatewayClientHeadersSchema,
     response: CurrentUserResponseSchema,
     responseDescription: "Current user state.",
     errors: { 402: NO_PLAN, 404: NO_END_USERS }
@@ -18868,6 +19051,7 @@ var CATALOG = {
       status: external_exports.enum(USAGE_STATUSES).optional(),
       provider: external_exports.string().optional(),
       user: external_exports.string().optional(),
+      install: external_exports.string().optional().meta({ description: "Only events of this install: an App Attest key id." }),
       model: external_exports.string().optional(),
       before_id: BeforeIdSchema
     }),
@@ -19046,7 +19230,7 @@ var CATALOG = {
     security: "management",
     params: APP_PARAM,
     query: RangeQuerySchema.extend({
-      by: external_exports.enum(USAGE_BREAKDOWN_DIMENSIONS).default("model").meta({ description: "Which dimension to group by. Defaults to model." }),
+      by: external_exports.enum(USAGE_BREAKDOWN_DIMENSIONS).default("model").meta({ description: "Which dimension to group by. Defaults to model. install groups an App Attest application's traffic by the install \u2014 the App Attest key \u2014 that made it; server applications have none." }),
       limit: PageLimitSchema
     }),
     response: BreakdownResponseSchema,
@@ -21606,7 +21790,12 @@ function list(command, result, style2) {
 }
 function show(command, result, style2) {
   if (command === "app show" && "app" in result && !("guidance" in result)) {
-    return [style2.headline(`${result.app.name} (${result.app.id})`), "", style2.json(result)];
+    return [
+      style2.headline(`${result.app.name} (${result.app.id})`),
+      ...warnings(result.app.warnings ?? [], style2),
+      "",
+      style2.json(result)
+    ];
   }
   if ("slug" in result)
     return [
@@ -21784,7 +21973,8 @@ function app(command, result, context, style2) {
         ],
         style2
       ),
-      ...notes(result.limitations)
+      ...notes(result.limitations),
+      ...warnings(result.warnings ?? [], style2)
     ];
   if ("definition" in result) {
     const dryRun = "dryRun" in result;
@@ -21811,6 +22001,14 @@ function app(command, result, context, style2) {
     return written(command, result, context, style2);
   return [style2.json(result)];
 }
+function warnings(values, style2) {
+  if (!values.length) return [];
+  return [
+    "",
+    style2.warn("Warnings"),
+    ...values.map((warning) => `- ${warning.message}${warning.docs_url ? ` See ${warning.docs_url}` : ""}`)
+  ];
+}
 var notes = (values) => values.length ? ["", ...values.map((value) => `- ${value}`)] : [];
 function written(command, result, context, style2) {
   const parsed = AppConfigSchema.safeParse(result.app.config);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxceem/agw",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "type": "module",
   "description": "Manage App AI Gateway from a terminal or coding agent: providers, iOS and server apps, usage, and self-hosted deployment on Cloudflare",
   "keywords": [
@@ -26,6 +26,8 @@
   },
   "bugs": "https://github.com/maxceem/app-ai-gateway/issues",
   "upgradeFrom": [
+    "0.7.2",
+    "0.7.1",
     "0.7.0",
     "0.6.4",
     "0.6.3",