Priced tools and metered usage

import { defineTool, DuneaClient } from '@dunea/plugin-sdk';

declare function getAccessToken(installId: string): Promise<string>;
declare function buyLabel(orderId: string, idempotencyKey: string): Promise<{ trackingNumber: string; labelUrl: string }>;

export const createShippingLabel = defineTool({
  name: 'create_shipping_label',
  description:
    'Buy and print a shipping label for a paid order, and add the tracking number to the order. ' +
    'Use when the owner asks to ship an order. Costs 2 credits per label.',
  input: {
    type: 'object',
    properties: {
      orderId: { type: 'string', description: 'The order id' },
    },
    required: ['orderId'],
  },
  handler: async (input, request) => {
    // request.id is the charge key: a retried call has the same id and is charged once.
    // Pass it on, so a retry doesn't buy a second label from your carrier either.
    const label = await buyLabel(input.orderId, request.id);
    const dunea = new DuneaClient({ accessToken: await getAccessToken(request.installId) });

    await dunea.orders.fulfil(input.orderId, { trackingNumber: label.trackingNumber });

    return { output: `Label printed. Tracking number ${label.trackingNumber}.`, data: { labelUrl: label.labelUrl } };
  },
});

import { definePlugin } from '@dunea/plugin-sdk';
import { createShippingLabel } from './src/tools';

export const manifest = definePlugin({
  // ...
  permissions: ['orders:read', 'orders:write'],
  webhookUrl: 'https://labels.example.com/dunea',
  agentTools: [{ ...createShippingLabel.manifest, price: { credits: 2 } }],
});

{
  "agentTools": [
    {
      "name": "create_shipping_label",
      "description": "Buy and print a shipping label for a paid order… Costs 2 credits per label.",
      "input": { "type": "object", "properties": { "orderId": { "type": "string", "description": "The order id" } }, "required": ["orderId"] },
      "price": { "credits": 2 }
    }
  ]
}

{
  "usage": {
    "unit": "label",
    "maxCreditsPerUnit": 2,
    "description": "Each shipping label you print costs up to 2 credits, depending on the carrier.",
    "suggestedMonthlyCapCredits": 100
  }
}

interface UsageReport {
  /** How many units (manifest usage.unit), > 0. */
  units: number;
  /** Price per unit in credits, ≤ manifest usage.maxCreditsPerUnit. */
  creditsPerUnit: number;
  /** Shown on the owner's statement ("Printed 3 shipping labels"). ≤ 120 chars. */
  description: string;
  /** Your unique key for this charge (≤ 100 chars); a retry with the same key is charged once. */
  idempotencyKey: string;
}

interface UsageReceipt {
  chargeId: string;
  credits: number;
  /** charged | waived (dev installs and your own apps are never charged) */
  status: 'charged' | 'waived';
  /** Credits left under the owner's cap this month. */
  remainingCapCredits: number;
}

import { DuneaApiError, DuneaClient, type UsageRefusal } from '@dunea/plugin-sdk';

// After printing three labels for order 1042:
declare const accessToken: string; // the install's access token (from plugin.installed)

const dunea = new DuneaClient({ accessToken });

try {
  const receipt = await dunea.reportUsage({
    units: 3,
    creditsPerUnit: 1.5,
    description: 'Printed 3 shipping labels for order #1042',
    idempotencyKey: 'order-1042-labels', // the same key on a retry is charged once
  });

  console.log(receipt.status, receipt.credits, receipt.remainingCapCredits);
} catch (err) {
  if (err instanceof DuneaApiError && err.status === 402) {
    // The owner's cap or balance can't cover it. Nothing was charged:
    // pause the paid work and tell the owner in your panel.
    const refusal = err.body as UsageRefusal;
    console.warn(refusal.error, refusal.remainingCapCredits);
  } else {
    throw err;
  }
}

interface UsageRefusal {
  error: 'spend_cap_reached' | 'insufficient_credits';
  message: string;
  remainingCapCredits: number;
}

interface UsageSummary {
  month: string;
  capCredits: number | null;
  usedCredits: number;
  charges: { id: string; item: string; units: number; credits: number; description: string | null; status: string; at: string }[];
}