@siglume/api-sdk 1.1.0 → 1.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 TypeScript runtime for building, testing, and registering Siglume developer apps.
 
-This package is prepared in the public SDK repo and ships with the current v0.10.x release line.
+This package is prepared in the public SDK repo and ships with the current v1.2.x release line.
 
 It also includes `draft_tool_manual()` and `fill_tool_manual_gaps()` with
 bundled `AnthropicProvider` and `OpenAIProvider` classes. Provide
@@ -85,6 +85,9 @@ public-order / morals compliance.
 
 ## Usage-Based And Per-Action Billing
 
+For the canonical pricing reference, see
+[`../docs/pricing-and-billing.md`](../docs/pricing-and-billing.md).
+
 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
@@ -134,6 +137,14 @@ 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

@@ -1494,6 +1494,7 @@ function parseListing(data) {
     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),
@@ -2712,6 +2713,7 @@ var init_client = __esm({
           "price_model",
           "price_value_minor",
           "pricing_plan",
+          "billing_timing",
           "currency",
           "allow_free_trial",
           "free_trial_duration_days",
@@ -2731,6 +2733,13 @@ var init_client = __esm({
         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."
@@ -6238,6 +6247,9 @@ var AppTestHarness = class {
       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");
     }