@agorio/plugin-procurement 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agorio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,50 @@
+# @agorio/plugin-procurement
+
+B2B procurement tooling for [Agorio](https://www.npmjs.com/package/@agorio/sdk) AI shopping agents.
+
+- **PO# tracking** — assign a purchase-order number to every cart, optionally gate `submit_payment` on its presence
+- **Vendor management** — resolve merchant domain → vendor record (payment terms, tax category, preferred-supplier flag)
+- **Expense categorization** — tag carts with one of your configured expense categories
+- **Audit-friendly events** — emits a `procurement_completed` event on successful checkout so the [`@agorio/plugin-audit-trail`](https://www.npmjs.com/package/@agorio/plugin-audit-trail) picks up PO# + vendor + category for free
+
+```bash
+npm install @agorio/sdk @agorio/plugin-procurement
+```
+
+```ts
+import { ShoppingAgent } from '@agorio/sdk';
+import { createProcurementPlugin } from '@agorio/plugin-procurement';
+
+const procurement = createProcurementPlugin({
+  vendors: [
+    { id: 'acme', name: 'Acme Office Supplies', domain: 'acme.com', paymentTerms: 'NET-30', taxCategory: 'office', preferred: true },
+    { id: 'staples', name: 'Staples', domain: 'staples.com', paymentTerms: 'NET-15', taxCategory: 'office' },
+  ],
+  expenseCategories: ['office-supplies', 'it-equipment', 'furniture'],
+  poNumberPrefix: 'PO-2026',
+  poNumberStrategy: 'sequential',
+  requirePoOnCheckout: true,
+});
+
+const agent = new ShoppingAgent({ llm, plugins: [procurement] });
+```
+
+## Configuration
+
+| Key                    | Type                                   | Description |
+| ---------------------- | -------------------------------------- | --- |
+| `vendors`              | `VendorConfig[]`                       | Known vendors, indexed by domain. |
+| `expenseCategories`    | `string[]`                             | Allowed values for `categorize_expense`. |
+| `poNumberPrefix`       | `string`                               | Optional prefix on generated PO numbers (default `'PO'`). |
+| `poNumberStrategy`     | `'sequential' \| 'uuid' \| () => string` | How to generate PO numbers (default `'sequential'`). |
+| `requirePoOnCheckout`  | `boolean`                              | Block `submit_payment` if the current cart has no PO# (default `false`). |
+
+## Tools exposed to the LLM
+
+- `assign_po_number` — `{ }` → `{ poNumber }`
+- `lookup_vendor` — `{ domain }` → `{ vendor }` (or `{ error }`)
+- `categorize_expense` — `{ category }` → `{ assigned: true, category }`
+
+## License
+
+MIT — same as the rest of Agorio's plugins.

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import type { EnterprisePlugin, PluginManifest } from '@agorio/sdk';
+export declare const PLUGIN_MANIFEST: PluginManifest;
+export interface VendorConfig {
+    id: string;
+    name: string;
+    domain: string;
+    paymentTerms?: string;
+    taxCategory?: string;
+    preferred?: boolean;
+    metadata?: Record<string, unknown>;
+}
+export type PoNumberStrategy = 'sequential' | 'uuid' | (() => string);
+export interface ProcurementConfig {
+    vendors?: VendorConfig[];
+    expenseCategories?: string[];
+    poNumberPrefix?: string;
+    poNumberStrategy?: PoNumberStrategy;
+    requirePoOnCheckout?: boolean;
+    onProcurementCompleted?: (event: ProcurementCompletedEvent) => void;
+}
+export interface ProcurementCompletedEvent {
+    poNumber: string;
+    vendorId: string | null;
+    category: string | null;
+    amount: number;
+    currency: string;
+    merchant: string | null;
+    timestamp: number;
+}
+export declare function createProcurementPlugin(config?: ProcurementConfig): EnterprisePlugin;

package/dist/index.js

@@ -0,0 +1,166 @@
+import { randomUUID } from 'node:crypto';
+export const PLUGIN_MANIFEST = {
+    version: '0.1.0',
+    author: 'Agorio',
+    category: 'governance',
+    tier: 'pro',
+};
+export function createProcurementPlugin(config = {}) {
+    const vendorsByDomain = new Map();
+    for (const v of config.vendors ?? []) {
+        vendorsByDomain.set(normalizeDomain(v.domain), v);
+    }
+    const expenseCategorySet = new Set(config.expenseCategories ?? []);
+    const prefix = config.poNumberPrefix ?? 'PO';
+    const strategy = config.poNumberStrategy ?? 'sequential';
+    let sequentialCounter = 0;
+    /** Cart tags keyed by `<merchant_domain>` (one in-flight tag per merchant). */
+    const cartTags = new Map();
+    let pluginCtx;
+    function getOrCreateTag(merchant) {
+        const key = merchant ?? '__none__';
+        let tag = cartTags.get(key);
+        if (!tag) {
+            tag = { poNumber: null, vendorId: null, category: null };
+            cartTags.set(key, tag);
+        }
+        return tag;
+    }
+    function generatePoNumber() {
+        if (typeof strategy === 'function')
+            return strategy();
+        if (strategy === 'uuid')
+            return `${prefix}-${randomUUID()}`;
+        sequentialCounter++;
+        return `${prefix}-${String(sequentialCounter).padStart(6, '0')}`;
+    }
+    return {
+        name: 'procurement',
+        description: 'Procurement tooling — assign purchase-order numbers, look up vendor info, and categorize the active cart\'s expense. Use `assign_po_number` before checkout if PO numbers are required.',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['assign_po_number', 'lookup_vendor', 'categorize_expense'],
+                    description: 'Procurement action to perform.',
+                },
+                domain: {
+                    type: 'string',
+                    description: 'Merchant domain (for `lookup_vendor`).',
+                },
+                category: {
+                    type: 'string',
+                    description: 'Expense category (for `categorize_expense`). Must be one of the configured categories.',
+                },
+            },
+            required: ['action'],
+        },
+        manifest: PLUGIN_MANIFEST,
+        handler(args) {
+            const action = String(args.action);
+            switch (action) {
+                case 'assign_po_number': {
+                    const merchant = pluginCtx?.getActiveMerchant() ?? null;
+                    const tag = getOrCreateTag(merchant);
+                    tag.poNumber = generatePoNumber();
+                    if (merchant) {
+                        const vendor = vendorsByDomain.get(normalizeDomain(merchant));
+                        if (vendor)
+                            tag.vendorId = vendor.id;
+                    }
+                    return { poNumber: tag.poNumber, vendorId: tag.vendorId };
+                }
+                case 'lookup_vendor': {
+                    const domain = String(args.domain ?? pluginCtx?.getActiveMerchant() ?? '');
+                    if (!domain)
+                        return { error: 'lookup_vendor: `domain` is required (no active merchant either)' };
+                    const vendor = vendorsByDomain.get(normalizeDomain(domain));
+                    if (!vendor)
+                        return { error: `Unknown vendor for domain: ${domain}` };
+                    return { vendor };
+                }
+                case 'categorize_expense': {
+                    const category = String(args.category ?? '');
+                    if (!category)
+                        return { error: 'categorize_expense: `category` is required' };
+                    if (expenseCategorySet.size > 0 && !expenseCategorySet.has(category)) {
+                        return {
+                            error: `Unknown expense category "${category}". Allowed: ${[...expenseCategorySet].join(', ')}`,
+                        };
+                    }
+                    const merchant = pluginCtx?.getActiveMerchant() ?? null;
+                    const tag = getOrCreateTag(merchant);
+                    tag.category = category;
+                    return { assigned: true, category };
+                }
+                default:
+                    return { error: `Unknown procurement action: ${action}` };
+            }
+        },
+        onInit(context) {
+            pluginCtx = context;
+        },
+        onBeforeToolCall(toolName, _args, context) {
+            if (toolName !== 'submit_payment')
+                return { allow: true };
+            if (!config.requirePoOnCheckout)
+                return { allow: true };
+            const merchant = context.getActiveMerchant();
+            const tag = cartTags.get(merchant ?? '__none__');
+            if (!tag || !tag.poNumber) {
+                return {
+                    allow: false,
+                    reason: 'PO# required for this transaction. Call the `procurement` tool with action `assign_po_number` first.',
+                };
+            }
+            return { allow: true };
+        },
+        onAfterToolCall(toolName, _args, result, context) {
+            if (toolName !== 'submit_payment')
+                return;
+            if (!result || typeof result !== 'object' || !('orderId' in result))
+                return;
+            const merchant = context.getActiveMerchant();
+            const tag = cartTags.get(merchant ?? '__none__');
+            const cart = context.getCart();
+            const amount = parseFloat(cart.subtotal.amount);
+            const event = {
+                poNumber: tag?.poNumber ?? '',
+                vendorId: tag?.vendorId ?? null,
+                category: tag?.category ?? null,
+                amount,
+                currency: cart.subtotal.currency,
+                merchant,
+                timestamp: Date.now(),
+            };
+            config.onProcurementCompleted?.(event);
+            // Reset the tag after a successful checkout so the next purchase on the
+            // same merchant starts fresh.
+            cartTags.delete(merchant ?? '__none__');
+        },
+        getState() {
+            return {
+                cartTags: Array.from(cartTags.entries()).map(([merchant, tag]) => ({
+                    merchant,
+                    ...tag,
+                })),
+                sequentialCounter,
+            };
+        },
+        hydrate(state) {
+            cartTags.clear();
+            const tags = Array.isArray(state.cartTags) ? state.cartTags : [];
+            for (const entry of tags) {
+                const { merchant, ...rest } = entry;
+                cartTags.set(merchant, rest);
+            }
+            if (typeof state.sequentialCounter === 'number') {
+                sequentialCounter = state.sequentialCounter;
+            }
+        },
+    };
+}
+function normalizeDomain(d) {
+    return d.replace(/^https?:\/\//, '').replace(/\/+$/, '').toLowerCase();
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@agorio/plugin-procurement",
+  "version": "0.1.0",
+  "description": "B2B procurement plugin for Agorio SDK — PO# tracking, vendor management, and expense categorization for AI shopping agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@agorio/sdk": "^0.7.0"
+  },
+  "devDependencies": {
+    "@agorio/sdk": "file:../..",
+    "@types/node": "^22.9.0",
+    "typescript": "^5.6.3",
+    "vitest": "^4.0.17"
+  },
+  "keywords": [
+    "agorio",
+    "ucp",
+    "acp",
+    "ai-agent",
+    "shopping-agent",
+    "procurement",
+    "b2b",
+    "purchase-order",
+    "vendor",
+    "expense",
+    "enterprise"
+  ],
+  "author": "Agorio",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Nolpak14/agorio",
+    "directory": "plugins/procurement"
+  }
+}