@oneshot-agent/mcp-server 0.39.0 → 0.40.0

package/dist/tools/physical-mail.js

@@ -0,0 +1,105 @@
+/**
+ * The two Physical Mail steps that a generated route tool cannot carry (#1883): the send,
+ * which needs an idempotency key header beside the quote id and the approval id, and the
+ * artwork upload, whose body is a raw PDF, PNG or JPEG. Both go through the SDK's
+ * `physicalMail` (libs/agent-sdk/src/physical-mail.ts). The other seven routes (validate,
+ * preview, quote, approve, recover, order, cancel) are generated from the declaration.
+ */
+/** The route's own limit (`uploadArtwork` in services/physical-mail/service.ts): 20 MB. */
+export const PHYSICAL_MAIL_ASSET_LIMIT_BYTES = 20 * 1024 * 1024;
+export const PHYSICAL_MAIL_ASSET_TYPES = ["application/pdf", "image/png", "image/jpeg"];
+export const physicalMailSendTool = {
+    name: "oneshot_physical_mail_send",
+    description: "Print and post an approved mailpiece. Paid: the quote's total_usdc is charged (see Pricing), and the receipt is on the order. " +
+        "Needs the quote_id from oneshot_physical_mail_preview and the approval_id from oneshot_physical_mail_approve. " +
+        "Give an idempotency_key you keep: a retry with the same key returns the same order instead of sending twice, and " +
+        "oneshot_physical_mail_recover finds the order by it after a timeout. Returns the order (order_id, order_status, " +
+        "payment_status, receipt_id). Delivery is a postal observation, never evidence the mail was read.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            quote_id: { type: "string", description: "Quote id from oneshot_physical_mail_preview" },
+            approval_id: { type: "string", description: "Approval id from oneshot_physical_mail_approve (the quote's own approval)" },
+            idempotency_key: {
+                type: "string",
+                description: "A key you persist for this send (1-255 characters: letters, digits, _ . : -). Reuse it to retry safely.",
+            },
+            memo: { type: "string", description: "Why this mail is being sent (audit trail, max 1000 characters; optional)" },
+            max_cost: { type: "number", description: "Refuse to pay more than this many USDC (optional)" },
+            policy_approval_id: {
+                type: "string",
+                description: "Only when retrying a send the action policy held: the approval_id from the approval_required error, once a human approved it. Not the quote's approval_id.",
+            },
+        },
+        required: ["quote_id", "approval_id", "idempotency_key"],
+    },
+};
+export async function handlePhysicalMailSend(agent, args) {
+    return agent.physicalMail.send({
+        quote_id: args.quote_id,
+        approval_id: args.approval_id,
+        idempotencyKey: args.idempotency_key,
+        memo: args.memo,
+        maxCost: args.max_cost,
+        approvalId: args.policy_approval_id,
+    });
+}
+export const physicalMailUploadTool = {
+    name: "oneshot_physical_mail_upload",
+    description: "Upload print-ready artwork for a letter or postcard and get the asset id that oneshot_physical_mail_preview takes in " +
+        "artwork.file (a letter needs a PDF) or artwork.front and artwork.back (a postcard). Free. The file is sent as base64; " +
+        "it must decode to at most 20 MB. An asset is immutable: upload a new one to change the artwork.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            content: { type: "string", description: "The file, base64-encoded (standard or URL-safe alphabet, padding optional)" },
+            content_type: { type: "string", enum: [...PHYSICAL_MAIL_ASSET_TYPES], description: "The file's media type" },
+        },
+        required: ["content", "content_type"],
+    },
+};
+/** Decodes the base64 `content`, refusing anything that is not base64 or that would exceed the route's limit before any bytes are sent. */
+export function decodeArtwork(args) {
+    const mime = args.content_type;
+    if (!PHYSICAL_MAIL_ASSET_TYPES.includes(mime)) {
+        throw new Error(`oneshot_physical_mail_upload: content_type must be one of ${PHYSICAL_MAIL_ASSET_TYPES.join(", ")}`);
+    }
+    if (typeof args.content !== "string" || args.content.length === 0)
+        throw new Error("oneshot_physical_mail_upload: content is required");
+    const text = args.content.replace(/\s+/g, "");
+    const size = base64Size(text);
+    if (size === null)
+        throw new Error("oneshot_physical_mail_upload: content is not base64");
+    if (size > PHYSICAL_MAIL_ASSET_LIMIT_BYTES) {
+        throw new Error(`oneshot_physical_mail_upload: the file is ${size} bytes; the limit is ${PHYSICAL_MAIL_ASSET_LIMIT_BYTES} bytes (20 MB)`);
+    }
+    const data = Buffer.from(text, "base64");
+    if (data.length === 0)
+        throw new Error("oneshot_physical_mail_upload: content decodes to nothing");
+    // The decoder is lenient; the structural check above is what bounds the size, and this guards the limit regardless.
+    if (data.length > PHYSICAL_MAIL_ASSET_LIMIT_BYTES) {
+        throw new Error(`oneshot_physical_mail_upload: the file is ${data.length} bytes; the limit is ${PHYSICAL_MAIL_ASSET_LIMIT_BYTES} bytes (20 MB)`);
+    }
+    return { data: new Uint8Array(data), mime: mime };
+}
+/**
+ * The decoded size of structurally valid base64 (standard or URL-safe alphabet, padding optional), or null.
+ * `Buffer.from(text, "base64")` tolerates a length one past a quartet, missing, short and excess padding
+ * (`AAAAA`, `AAA==`, `AAAA==`), so counting characters and subtracting the `=`s would undercount such
+ * input; the bound has to come from a shape the decoder cannot read differently.
+ */
+export function base64Size(text) {
+    if (!/^[A-Za-z0-9+/_-]*={0,2}$/.test(text))
+        return null;
+    const body = text.replace(/=+$/, "");
+    const padding = text.length - body.length;
+    const rem = body.length % 4;
+    // A body is never one character past a quartet, and padding, when given, is exactly what completes the last one.
+    if (body.length === 0 || rem === 1 || (padding > 0 && padding !== (4 - rem) % 4))
+        return null;
+    return Math.floor((body.length * 3) / 4);
+}
+export async function handlePhysicalMailUpload(agent, args) {
+    const { data, mime } = decodeArtwork(args);
+    return agent.physicalMail.uploadArtwork(data, mime);
+}