@siglume/api-sdk 1.0.0 → 1.2.0

package/README.md

@@ -83,6 +83,65 @@ includes runtime checks, contract checks, external OAuth declaration checks, pri
 rules, and a mandatory fail-closed LLM legal review for law compliance plus
 public-order / morals compliance.
 
+## Usage-Based And Per-Action Billing
+
+Use `price_model: PriceModel.USAGE_BASED` or `PriceModel.PER_ACTION` when the
+API must execute before the final operation is known. These listings are free to
+invoke up front. Your adapter returns the executed operation in
+`ExecutionResult.receipt_summary`; the matching `pricing_plan` item sets the
+charge:
+
+```ts
+return {
+  success: true,
+  output: { posted: true, post_url: "https://x.com/..." },
+  units_consumed: 1,
+  amount_minor: 20,
+  currency: "JPY",
+  receipt_summary: {
+    operation: "url_post",
+    amount_minor: 20,
+    currency: "JPY",
+  },
+};
+```
+
+Set `price_value_minor: 0` when prices vary by operation, and publish a
+buyer-facing `pricing_plan` so API Store and Game API Store can show the plan.
+`pricing_plan.items` is required for `usage_based` and `per_action` listings:
+
+```ts
+pricing_plan: {
+  display_name: "Operation prices",
+  currency: "JPY",
+  free_upfront_invocation: true,
+  items: [
+    { key: "connection_check", label: "Connection check", price_minor: 0 },
+    { key: "dry_run", label: "Dry-run preview", price_minor: 0 },
+    { key: "text_post", label: "Text post", price_minor: 15 },
+    { key: "url_post", label: "URL post", price_minor: 20 },
+    { key: "reply", label: "Reply", price_minor: 30 },
+  ],
+}
+```
+
+The `pricing_plan` is authoritative. If the adapter returns a conflicting
+positive amount, the platform rejects the call instead of charging an arbitrary
+API-declared amount. `0` is valid for free operations. For JPY/JPYC billing,
+positive operation prices must be at least `15` minor units; `1` through `14`
+are rejected by the SDK and platform because platform-sponsored gas can exceed
+the fee.
+`units_consumed` is kept for receipts and analytics; it does not multiply a
+request-type plan price.
+
+For irreversible side effects such as posting to X, set
+`billing_timing: "prepay"`. The platform first calls your API as a quote
+(`execution_kind="quote"` / `dry_run=true`), reads `billingPreview.operation`
+and `draftToken`, collects the direct payment for that pricing-plan operation,
+then calls the ACTION endpoint with the same token as `commit_token`. If payment
+fails, the ACTION call is never made. Use the default `"post"` timing only for
+read-only or reversible usage.
+
 Company-name publishing is founder-only in the Phase 2 MVP. Use
 `publisher_type: "company"` with `company_id` in `app_manifest.yaml`, or pass
 `--company <company_id>` to the CLI. Paid company listings require the

package/dist/bin/siglume.cjs

@@ -176,6 +176,61 @@ var init_utils = __esm({
   }
 });
 
+// src/types.ts
+var PermissionClass, ApprovalMode, Environment, PriceModel, AppCategory, MINIMUM_JPY_OPERATION_PRICE_MINOR, ToolManualPermissionClass, SettlementMode;
+var init_types = __esm({
+  "src/types.ts"() {
+    "use strict";
+    PermissionClass = {
+      READ_ONLY: "read-only",
+      ACTION: "action",
+      PAYMENT: "payment",
+      /** @deprecated Use READ_ONLY. Behaves identically. */
+      RECOMMENDATION: "recommendation"
+    };
+    ApprovalMode = {
+      AUTO: "auto",
+      BUDGET_BOUNDED: "budget-bounded",
+      ALWAYS_ASK: "always-ask",
+      DENY: "deny"
+    };
+    Environment = {
+      SANDBOX: "sandbox",
+      LIVE: "live"
+    };
+    PriceModel = {
+      FREE: "free",
+      SUBSCRIPTION: "subscription",
+      ONE_TIME: "one_time",
+      BUNDLE: "bundle",
+      USAGE_BASED: "usage_based",
+      PER_ACTION: "per_action"
+    };
+    AppCategory = {
+      COMMERCE: "commerce",
+      BOOKING: "booking",
+      CRM: "crm",
+      FINANCE: "finance",
+      DOCUMENT: "document",
+      COMMUNICATION: "communication",
+      MONITORING: "monitoring",
+      OTHER: "other"
+    };
+    MINIMUM_JPY_OPERATION_PRICE_MINOR = 15;
+    ToolManualPermissionClass = {
+      READ_ONLY: "read_only",
+      ACTION: "action",
+      PAYMENT: "payment"
+    };
+    SettlementMode = {
+      STRIPE_CHECKOUT: "stripe_checkout",
+      STRIPE_PAYMENT_INTENT: "stripe_payment_intent",
+      POLYGON_MANDATE: "polygon_mandate",
+      EMBEDDED_WALLET_CHARGE: "embedded_wallet_charge"
+    };
+  }
+});
+
 // src/webhooks.ts
 function isRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -1297,6 +1352,58 @@ function validateSaveDataSchema(schema, fieldName) {
     }
   }
 }
+function validatePricingPlanFloor(plan, defaultCurrency) {
+  if (plan === void 0 || plan === null) {
+    return;
+  }
+  if (!isRecord(plan)) {
+    throw new SiglumeClientError("AppManifest.pricing_plan must be an object when provided.");
+  }
+  const items = plan.items;
+  if (items === void 0 || items === null) {
+    return;
+  }
+  if (!Array.isArray(items)) {
+    throw new SiglumeClientError("AppManifest.pricing_plan.items must be an array when provided.");
+  }
+  const planCurrency = String(plan.currency ?? defaultCurrency ?? "").trim().toUpperCase();
+  const seenKeys = /* @__PURE__ */ new Set();
+  items.forEach((item, index) => {
+    if (!isRecord(item)) {
+      throw new SiglumeClientError(`AppManifest.pricing_plan.items[${index}] must be an object.`);
+    }
+    const itemKey = String(
+      item.key ?? item.operation ?? item.operation_key ?? item.request_type ?? item.receipt_code ?? item.action ?? ""
+    ).trim();
+    if (!itemKey) {
+      throw new SiglumeClientError(`AppManifest.pricing_plan.items[${index}].key is required.`);
+    }
+    if (seenKeys.has(itemKey)) {
+      throw new SiglumeClientError(`AppManifest.pricing_plan.items[${index}].key duplicates ${itemKey}.`);
+    }
+    seenKeys.add(itemKey);
+    const amountRaw = item.price_minor ?? item.amount_minor ?? item.cost_minor ?? item.value_minor;
+    if (amountRaw === void 0 || amountRaw === null) {
+      throw new SiglumeClientError(`AppManifest.pricing_plan.items[${index}].price_minor is required.`);
+    }
+    const amountMinor = typeof amountRaw === "number" ? amountRaw : typeof amountRaw === "string" && amountRaw.trim() ? Number(amountRaw) : NaN;
+    if (!Number.isInteger(amountMinor)) {
+      throw new SiglumeClientError(`AppManifest.pricing_plan.items[${index}].price_minor must be an integer.`);
+    }
+    if (amountMinor < 0) {
+      throw new SiglumeClientError(`AppManifest.pricing_plan.items[${index}].price_minor must be zero or positive.`);
+    }
+    const currency = String(item.currency ?? planCurrency ?? defaultCurrency ?? "").trim().toUpperCase();
+    if (MINIMUM_JPY_OPERATION_PRICE_CURRENCIES.has(currency) && amountMinor > 0 && amountMinor < MINIMUM_JPY_OPERATION_PRICE_MINOR) {
+      throw new SiglumeClientError(
+        `AppManifest.pricing_plan.items[${index}].price_minor must be 0 or at least ${MINIMUM_JPY_OPERATION_PRICE_MINOR} for JPY/JPYC operation billing.`
+      );
+    }
+  });
+}
+function pricingPlanHasItems(plan) {
+  return isRecord(plan) && Array.isArray(plan.items) && plan.items.length > 0;
+}
 function buildToolManualQualityReport(payload) {
   const qualityBlock = isRecord(payload.quality) ? payload.quality : payload;
   const issues = [];
@@ -1372,6 +1479,7 @@ function buildUrl(baseUrl, path, params) {
 }
 function parseListing(data) {
   const metadata = isRecord(data.metadata) ? data.metadata : {};
+  const pricing_plan = isRecord(data.pricing_plan) ? data.pricing_plan : isRecord(metadata.pricing_plan) ? metadata.pricing_plan : null;
   const persistence = isRecord(data.persistence) ? data.persistence : isRecord(metadata.persistence) ? metadata.persistence : {};
   return {
     listing_id: String(data.listing_id ?? data.id ?? ""),
@@ -1385,6 +1493,8 @@ function parseListing(data) {
     dry_run_supported: Boolean(data.dry_run_supported ?? false),
     price_model: stringOrNull(data.price_model),
     price_value_minor: Number(data.price_value_minor ?? 0),
+    pricing_plan,
+    billing_timing: String(data.billing_timing ?? metadata.billing_timing ?? "post"),
     currency: String(data.currency ?? "USD"),
     allow_free_trial: Boolean(data.allow_free_trial ?? false),
     free_trial_duration_days: Number(data.free_trial_duration_days ?? 30),
@@ -2482,10 +2592,11 @@ function cloneJsonLike(value) {
   }
   return value;
 }
-var DEFAULT_SIGLUME_API_BASE, RETRYABLE_STATUS_CODES, CursorPageResult, SiglumeClient;
+var DEFAULT_SIGLUME_API_BASE, RETRYABLE_STATUS_CODES, MINIMUM_JPY_OPERATION_PRICE_CURRENCIES, CursorPageResult, SiglumeClient;
 var init_client = __esm({
   "src/client.ts"() {
     "use strict";
+    init_types();
     init_errors();
     init_webhooks();
     init_web3();
@@ -2493,6 +2604,7 @@ var init_client = __esm({
     init_utils();
     DEFAULT_SIGLUME_API_BASE = "https://siglume.com/v1";
     RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+    MINIMUM_JPY_OPERATION_PRICE_CURRENCIES = /* @__PURE__ */ new Set(["JPY", "JPYC"]);
     CursorPageResult = class {
       items;
       next_cursor;
@@ -2600,6 +2712,8 @@ var init_client = __esm({
           "jurisdiction",
           "price_model",
           "price_value_minor",
+          "pricing_plan",
+          "billing_timing",
           "currency",
           "allow_free_trial",
           "free_trial_duration_days",
@@ -2616,6 +2730,16 @@ var init_client = __esm({
             payload[fieldName] = value;
           }
         }
+        if (payload.pricing_plan !== void 0 && (typeof payload.pricing_plan !== "object" || Array.isArray(payload.pricing_plan))) {
+          throw new SiglumeClientError("AppManifest.pricing_plan must be an object when provided.");
+        }
+        if (payload.billing_timing !== void 0 && payload.billing_timing !== null) {
+          const billingTiming = String(payload.billing_timing || "post").trim().toLowerCase();
+          if (billingTiming !== "post" && billingTiming !== "prepay") {
+            throw new SiglumeClientError("AppManifest.billing_timing must be 'post' or 'prepay'.");
+          }
+          payload.billing_timing = billingTiming;
+        }
         if (payload.store_vertical === void 0 || payload.store_vertical === null) {
           throw new SiglumeClientError(
             "AppManifest.store_vertical is required. Choose 'api' for normal API Store listings or 'game' for API games."
@@ -2631,6 +2755,13 @@ var init_client = __esm({
           throw new SiglumeClientError(`AppManifest.currency must be 'USD' or 'JPY'. Got ${String(payload.currency)}.`);
         }
         payload.currency = currency;
+        if (payload.pricing_plan !== void 0) {
+          validatePricingPlanFloor(payload.pricing_plan, currency);
+        }
+        const priceModel = String(payload.price_model ?? "free").trim().toLowerCase();
+        if ((priceModel === "usage_based" || priceModel === "per_action") && !pricingPlanHasItems(payload.pricing_plan)) {
+          throw new SiglumeClientError("AppManifest.pricing_plan.items is required for usage_based/per_action pricing.");
+        }
         if (payload.allow_free_trial === void 0 || payload.allow_free_trial === null) {
           throw new SiglumeClientError(
             "AppManifest.allow_free_trial is required. Pass true to offer a Plus/Pro buyer free trial or false to disable trials."
@@ -5305,53 +5436,8 @@ function stableValue(value) {
   return value;
 }
 
-// src/types.ts
-var PermissionClass = {
-  READ_ONLY: "read-only",
-  ACTION: "action",
-  PAYMENT: "payment",
-  /** @deprecated Use READ_ONLY. Behaves identically. */
-  RECOMMENDATION: "recommendation"
-};
-var ApprovalMode = {
-  AUTO: "auto",
-  BUDGET_BOUNDED: "budget-bounded",
-  ALWAYS_ASK: "always-ask",
-  DENY: "deny"
-};
-var Environment = {
-  SANDBOX: "sandbox",
-  LIVE: "live"
-};
-var PriceModel = {
-  FREE: "free",
-  SUBSCRIPTION: "subscription",
-  ONE_TIME: "one_time",
-  BUNDLE: "bundle",
-  USAGE_BASED: "usage_based",
-  PER_ACTION: "per_action"
-};
-var AppCategory = {
-  COMMERCE: "commerce",
-  BOOKING: "booking",
-  CRM: "crm",
-  FINANCE: "finance",
-  DOCUMENT: "document",
-  COMMUNICATION: "communication",
-  MONITORING: "monitoring",
-  OTHER: "other"
-};
-var ToolManualPermissionClass = {
-  READ_ONLY: "read_only",
-  ACTION: "action",
-  PAYMENT: "payment"
-};
-var SettlementMode = {
-  STRIPE_CHECKOUT: "stripe_checkout",
-  STRIPE_PAYMENT_INTENT: "stripe_payment_intent",
-  POLYGON_MANDATE: "polygon_mandate",
-  EMBEDDED_WALLET_CHARGE: "embedded_wallet_charge"
-};
+// src/runtime.ts
+init_types();
 
 // src/testing/recorder.ts
 var CASSETTE_VERSION = 1;
@@ -5743,6 +5829,7 @@ Actual:   ${requestSignature(requestRecord, ignoreBodyFields)}`
 };
 
 // src/tool-manual-validator.ts
+init_types();
 init_utils();
 var JURISDICTION_PATTERN = /^[A-Z]{2}(-[A-Z0-9]{1,3})?$/;
 var TOOL_NAME_RE = /^[A-Za-z0-9_]{3,64}$/;
@@ -6014,6 +6101,64 @@ function validate_tool_manual(manualInput) {
 // src/runtime.ts
 init_web3();
 var CAPABILITY_KEY_RE = /^[a-z0-9][a-z0-9-]*[a-z0-9]$/;
+var MINIMUM_JPY_OPERATION_PRICE_CURRENCIES2 = /* @__PURE__ */ new Set(["JPY", "JPYC"]);
+function pricingPlanFloorIssues(plan, defaultCurrency) {
+  const issues = [];
+  if (plan === void 0 || plan === null) {
+    return issues;
+  }
+  if (typeof plan !== "object" || Array.isArray(plan)) {
+    return ["pricing_plan must be an object when provided"];
+  }
+  const record = plan;
+  const items = record.items;
+  if (items === void 0 || items === null) {
+    return issues;
+  }
+  if (!Array.isArray(items)) {
+    return ["pricing_plan.items must be an array when provided"];
+  }
+  const planCurrency = String(record.currency ?? defaultCurrency ?? "").trim().toUpperCase();
+  const seenKeys = /* @__PURE__ */ new Set();
+  items.forEach((item, index) => {
+    if (typeof item !== "object" || item === null || Array.isArray(item)) {
+      issues.push(`pricing_plan.items[${index}] must be an object`);
+      return;
+    }
+    const itemRecord = item;
+    const itemKey = String(
+      itemRecord.key ?? itemRecord.operation ?? itemRecord.operation_key ?? itemRecord.request_type ?? itemRecord.receipt_code ?? itemRecord.action ?? ""
+    ).trim();
+    if (!itemKey) {
+      issues.push(`pricing_plan.items[${index}].key is required`);
+    } else if (seenKeys.has(itemKey)) {
+      issues.push(`pricing_plan.items[${index}].key duplicates ${itemKey}`);
+    } else {
+      seenKeys.add(itemKey);
+    }
+    const amountRaw = itemRecord.price_minor ?? itemRecord.amount_minor ?? itemRecord.cost_minor ?? itemRecord.value_minor;
+    if (amountRaw === void 0 || amountRaw === null) {
+      issues.push(`pricing_plan.items[${index}].price_minor is required`);
+      return;
+    }
+    const amountMinor = typeof amountRaw === "number" ? amountRaw : typeof amountRaw === "string" && amountRaw.trim() ? Number(amountRaw) : NaN;
+    if (!Number.isInteger(amountMinor)) {
+      issues.push(`pricing_plan.items[${index}].price_minor must be an integer`);
+      return;
+    }
+    if (amountMinor < 0) {
+      issues.push(`pricing_plan.items[${index}].price_minor must be zero or positive`);
+      return;
+    }
+    const currency = String(itemRecord.currency ?? planCurrency ?? defaultCurrency ?? "").trim().toUpperCase();
+    if (MINIMUM_JPY_OPERATION_PRICE_CURRENCIES2.has(currency) && amountMinor > 0 && amountMinor < MINIMUM_JPY_OPERATION_PRICE_MINOR) {
+      issues.push(
+        `pricing_plan.items[${index}].price_minor must be 0 or at least ${MINIMUM_JPY_OPERATION_PRICE_MINOR} for JPY/JPYC operation billing`
+      );
+    }
+  });
+  return issues;
+}
 function normalizeExecutionResult(result, executionKind) {
   return {
     success: Boolean(result.success),
@@ -6101,6 +6246,13 @@ var AppTestHarness = class {
     if (!manifest.example_prompts || manifest.example_prompts.length === 0) {
       issues.push("at least one example_prompt is recommended");
     }
+    issues.push(...pricingPlanFloorIssues(manifest.pricing_plan, String(manifest.currency ?? "USD")));
+    if (manifest.billing_timing !== void 0 && manifest.billing_timing !== "post" && manifest.billing_timing !== "prepay") {
+      issues.push("billing_timing must be 'post' or 'prepay'");
+    }
+    if ((manifest.price_model === PriceModel.USAGE_BASED || manifest.price_model === PriceModel.PER_ACTION) && (!manifest.pricing_plan || !Array.isArray(manifest.pricing_plan.items) || manifest.pricing_plan.items.length === 0)) {
+      issues.push("pricing_plan.items is required for usage_based/per_action pricing");
+    }
     if (manifest.permission_class === PermissionClass.ACTION || manifest.permission_class === PermissionClass.PAYMENT) {
       if (!manifest.dry_run_supported) {
         issues.push("action/payment apps should support dry_run");
@@ -6176,7 +6328,7 @@ var AppTestHarness = class {
       };
     }
     return {
-      experimental: manifest.price_model === PriceModel.USAGE_BASED || manifest.price_model === PriceModel.PER_ACTION,
+      experimental: false,
       usage_record,
       invoice_line_preview
     };