@forumone/throughline 0.0.0 → 1.0.0-next.0

package/dist/approvals/plugin.js

@@ -0,0 +1,92 @@
+import { getPluginRegistry } from '../plugin-contract/registry.js';
+import { createNamedLogger, defaultLogger } from '../logger/index.js';
+import { getAuditWriter } from '../audit/plugin.js';
+import { validateOptions } from './options.js';
+import { createApprovalsCollection } from './collection.js';
+import { attachApprovalResolver, createApprovalResolver } from './resolver.js';
+import { createActionEndpoint } from './endpoints/action.js';
+import { APPROVALS_TOOL_DESCRIPTORS, createGetApprovalStatusTool, createListMyRequestsTool, createListPendingApprovalsTool, createRequestApprovalTool, createRespondToApprovalTool, } from './tools/index.js';
+const PLUGIN_ID = '@forumone/throughline/approvals';
+const PLUGIN_VERSION = '0.1.0';
+const ACTION_HANDLER_SYMBOL = Symbol.for('@forumone/throughline/approvals-action-handler');
+export const approvalsPlugin = (rawOptions) => (incomingConfig) => {
+    if (rawOptions.enabled === false)
+        return incomingConfig;
+    const options = validateOptions(rawOptions);
+    const routePrefix = options.routePrefix ?? '/approvals';
+    const logger = createNamedLogger('approvals', options.logger ?? defaultLogger);
+    const collection = createApprovalsCollection({
+        ...(options.collectionSlug ? { slug: options.collectionSlug } : {}),
+        ...(options.usersSlug ? { usersSlug: options.usersSlug } : {}),
+        groupSlugs: options.groups.map((g) => g.slug),
+        ...(options.admin ? { admin: options.admin } : {}),
+    });
+    /*
+    Declared here, bound at `onInit` — `mcpPlugin` generates its per-key
+    checkboxes from these names and descriptions while the config is built, and
+    denies any tool it has no checkbox for. This plugin must therefore come
+    before `mcpPlugin` in the host's array.
+    */
+    options.mcpTools?.declare(APPROVALS_TOOL_DESCRIPTORS, { serverName: 'approvals' });
+    return {
+        ...incomingConfig,
+        collections: [...(incomingConfig.collections ?? []), collection],
+        endpoints: [
+            ...(incomingConfig.endpoints ?? []),
+            {
+                path: `${routePrefix}/action`,
+                method: 'get',
+                handler: async (req) => {
+                    const actionHandler = req.payload[ACTION_HANDLER_SYMBOL];
+                    if (!actionHandler) {
+                        return new Response('Approvals action handler not initialized', { status: 503 });
+                    }
+                    return actionHandler(req);
+                },
+            },
+        ],
+        onInit: async (payload) => {
+            if (incomingConfig.onInit) {
+                await incomingConfig.onInit(payload);
+            }
+            const registry = getPluginRegistry(payload);
+            registry.requireCapability('audit-log', PLUGIN_ID);
+            const auditWriter = getAuditWriter(payload);
+            const collectionSlug = options.collectionSlug;
+            const resolver = createApprovalResolver(collectionSlug ? { payload, collectionSlug } : { payload });
+            attachApprovalResolver(payload, resolver);
+            const actionEndpoint = createActionEndpoint({ options, auditWriter });
+            Object.defineProperty(payload, ACTION_HANDLER_SYMBOL, {
+                value: actionEndpoint.handler,
+                enumerable: false,
+                writable: false,
+                configurable: false,
+            });
+            const tools = [
+                createRequestApprovalTool({ payload, options, auditWriter }),
+                createRespondToApprovalTool({ payload, options, auditWriter }),
+                createGetApprovalStatusTool({ payload, options }),
+                createListPendingApprovalsTool({ payload, options }),
+                createListMyRequestsTool({ payload, options }),
+            ];
+            // Payload's own MCP plugin, and the only transport these tools have.
+            // `onInit` is both the earliest they can exist and still early enough
+            // that `mcpPlugin` reads the array populated.
+            options.mcpTools?.add(tools, { serverName: 'approvals', logger, audit: auditWriter });
+            registry.register({
+                id: PLUGIN_ID,
+                version: PLUGIN_VERSION,
+                capabilities: ['approvals', 'approval-resolver'],
+            });
+            logger.info('Approvals server ready', {
+                groups: options.groups.map((g) => g.slug),
+                expirationDays: options.expirationDays ?? 7,
+            });
+        },
+    };
+};
+// `createActionEndpoint` is exported from src/index.ts for clients who want
+// to expose the action handler separately (e.g. behind a branded router).
+// Most consumers won't need it — the plugin already registers the action
+// endpoint at `${routePrefix}/action`.
+//# sourceMappingURL=plugin.js.map

package/dist/approvals/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../../src/approvals/plugin.ts"],"names":[],"mappings":"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"}

package/dist/approvals/resolver.d.ts

@@ -0,0 +1,18 @@
+import type { Payload } from 'payload';
+import type { ApprovalResolver } from '../publishing/options.js';
+export interface CreateApprovalResolverOptions {
+    payload: Payload;
+    /** Override the approvals collection slug. Default: 'approvals'. */
+    collectionSlug?: string;
+}
+/**
+ * Builds the resolver that the publishing server consumes. Looks up the
+ * latest granted approval whose `targetVersion` matches the document
+ * version under consideration. Multiple decisions are sorted by `decidedAt`
+ * descending; first-decision-wins semantics mean the latest grant for a
+ * given version is what counts.
+ */
+export declare function createApprovalResolver(options: CreateApprovalResolverOptions): ApprovalResolver;
+/** Attaches the resolver to a Payload instance under the agreed symbol. */
+export declare function attachApprovalResolver(payload: object, resolver: ApprovalResolver): void;
+//# sourceMappingURL=resolver.d.ts.map

package/dist/approvals/resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.d.ts","sourceRoot":"","sources":["../../src/approvals/resolver.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,KAAK,EAAkB,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAKhF,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,OAAO,CAAA;IAChB,oEAAoE;IACpE,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,6BAA6B,GACrC,gBAAgB,CAyClB;AAED,2EAA2E;AAC3E,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,gBAAgB,GACzB,IAAI,CAON"}

package/dist/approvals/resolver.js

@@ -0,0 +1,57 @@
+import { DEFAULT_APPROVALS_SLUG } from './collection.js';
+import { APPROVALS_RESOLVER_SYMBOL } from './symbol.js';
+/**
+ * Builds the resolver that the publishing server consumes. Looks up the
+ * latest granted approval whose `targetVersion` matches the document
+ * version under consideration. Multiple decisions are sorted by `decidedAt`
+ * descending; first-decision-wins semantics mean the latest grant for a
+ * given version is what counts.
+ */
+export function createApprovalResolver(options) {
+    const { payload, collectionSlug = DEFAULT_APPROVALS_SLUG } = options;
+    return {
+        async getActiveApproval(collection, id, version) {
+            const result = await payload.find({
+                collection: collectionSlug,
+                where: {
+                    and: [
+                        { targetCollection: { equals: collection } },
+                        { targetId: { equals: id } },
+                        { targetVersion: { equals: version } },
+                        { status: { equals: 'granted' } },
+                    ],
+                },
+                limit: 1,
+                sort: '-decidedAt',
+            });
+            const approval = result.docs[0];
+            if (!approval)
+                return null;
+            const decidedAt = approval['decidedAt'];
+            if (typeof decidedAt !== 'string')
+                return null;
+            const decidedByRaw = approval['decidedBy'];
+            const decidedBy = typeof decidedByRaw === 'string'
+                ? decidedByRaw
+                : decidedByRaw && typeof decidedByRaw === 'object' && 'id' in decidedByRaw
+                    ? String(decidedByRaw.id)
+                    : '';
+            return {
+                id: String(approval['id']),
+                grantedAt: decidedAt,
+                grantedBy: decidedBy,
+                version: String(approval['targetVersion']),
+            };
+        },
+    };
+}
+/** Attaches the resolver to a Payload instance under the agreed symbol. */
+export function attachApprovalResolver(payload, resolver) {
+    Object.defineProperty(payload, APPROVALS_RESOLVER_SYMBOL, {
+        value: resolver,
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+}
+//# sourceMappingURL=resolver.js.map

package/dist/approvals/resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../../src/approvals/resolver.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,sBAAsB,EAAE,MAAM,iBAAiB,CAAA;AACxD,OAAO,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAA;AASvD;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAsC;IAEtC,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,sBAAsB,EAAE,GAAG,OAAO,CAAA;IAEpE,OAAO;QACL,KAAK,CAAC,iBAAiB,CAAC,UAAU,EAAE,EAAE,EAAE,OAAO;YAC7C,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC;gBAChC,UAAU,EAAE,cAAc;gBAC1B,KAAK,EAAE;oBACL,GAAG,EAAE;wBACH,EAAE,gBAAgB,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE;wBAC5C,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE;wBAC5B,EAAE,aAAa,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE;wBACtC,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE;qBAClC;iBACF;gBACD,KAAK,EAAE,CAAC;gBACR,IAAI,EAAE,YAAY;aACnB,CAAC,CAAA;YAEF,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAwC,CAAA;YACtE,IAAI,CAAC,QAAQ;gBAAE,OAAO,IAAI,CAAA;YAE1B,MAAM,SAAS,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAA;YACvC,IAAI,OAAO,SAAS,KAAK,QAAQ;gBAAE,OAAO,IAAI,CAAA;YAE9C,MAAM,YAAY,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAA;YAC1C,MAAM,SAAS,GACb,OAAO,YAAY,KAAK,QAAQ;gBAC9B,CAAC,CAAC,YAAY;gBACd,CAAC,CAAC,YAAY,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,IAAI,IAAI,YAAY;oBACxE,CAAC,CAAC,MAAM,CAAE,YAAgC,CAAC,EAAE,CAAC;oBAC9C,CAAC,CAAC,EAAE,CAAA;YAEV,OAAO;gBACL,EAAE,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;gBAC1B,SAAS,EAAE,SAAS;gBACpB,SAAS,EAAE,SAAS;gBACpB,OAAO,EAAE,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC;aAC3C,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,sBAAsB,CACpC,OAAe,EACf,QAA0B;IAE1B,MAAM,CAAC,cAAc,CAAC,OAAO,EAAE,yBAAyB,EAAE;QACxD,KAAK,EAAE,QAAQ;QACf,UAAU,EAAE,KAAK;QACjB,QAAQ,EAAE,KAAK;QACf,YAAY,EAAE,KAAK;KACpB,CAAC,CAAA;AACJ,CAAC"}

package/dist/approvals/symbol.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Where the approvals plugin attaches its resolver on the Payload instance,
+ * and where publishing's approval step looks for it when its own
+ * `approvalResolver` option is not set. That lookup is what lets a site add
+ * the approvals plugin without re-configuring publishing.
+ *
+ * One module, imported by both. Each side used to declare its own copy, kept in
+ * step by a comment, while they shipped as separate packages. Internal: a site
+ * never needs it.
+ */
+export declare const APPROVALS_RESOLVER_SYMBOL: unique symbol;
+//# sourceMappingURL=symbol.d.ts.map

package/dist/approvals/symbol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol.d.ts","sourceRoot":"","sources":["../../src/approvals/symbol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,eAAyD,CAAA"}

package/dist/approvals/symbol.js

@@ -0,0 +1,12 @@
+/**
+ * Where the approvals plugin attaches its resolver on the Payload instance,
+ * and where publishing's approval step looks for it when its own
+ * `approvalResolver` option is not set. That lookup is what lets a site add
+ * the approvals plugin without re-configuring publishing.
+ *
+ * One module, imported by both. Each side used to declare its own copy, kept in
+ * step by a comment, while they shipped as separate packages. Internal: a site
+ * never needs it.
+ */
+export const APPROVALS_RESOLVER_SYMBOL = Symbol.for('@forumone/throughline/approvals-resolver');
+//# sourceMappingURL=symbol.js.map

package/dist/approvals/symbol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol.js","sourceRoot":"","sources":["../../src/approvals/symbol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,MAAM,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAA"}

package/dist/approvals/tokens.d.ts

@@ -0,0 +1,48 @@
+/**
+ * HMAC-signed action tokens used in inline action emails (Approve / Decline /
+ * Request changes / Discuss). Each token is bound to one approval, one
+ * action, and one approver. Tokens are valid for a configurable window
+ * (default 14 days) and consumed via the `consumedTokens` array on the
+ * approval record so they can't be replayed.
+ *
+ * Crypto uses the Web Crypto API (`crypto.subtle`) so the same code runs
+ * in Node and edge runtimes.
+ */
+export type ActionTokenAction = 'approve' | 'decline' | 'changes' | 'discuss';
+export interface ActionToken {
+    approvalId: string;
+    action: ActionTokenAction;
+    approverId: string;
+    /** Issued-at timestamp in milliseconds since epoch. */
+    issuedAt: number;
+}
+/**
+ * Mints an action token. Returns a base64url-encoded payload with the
+ * format `<approvalId>:<action>:<approverId>:<issuedAt>:<signature>`.
+ */
+export declare function generateActionToken(token: ActionToken, secret: string): Promise<string>;
+export interface VerifyOptions {
+    /** Override the default 14-day token lifetime. */
+    maxAgeMs?: number;
+    /** Override "now" — useful in tests. Defaults to `Date.now()`. */
+    now?: number;
+}
+export type VerifyResult = {
+    ok: true;
+    token: ActionToken;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Verifies a base64url-encoded action token with constant-time signature
+ * comparison. Returns either the parsed token or a structured error.
+ */
+export declare function verifyActionToken(encoded: string, secret: string, options?: VerifyOptions): Promise<VerifyResult>;
+/**
+ * Returns the absolute URL an approver visits to invoke the action. The
+ * server-side endpoint (added by the plugin) verifies the token and
+ * presents a confirmation page before recording the decision.
+ */
+export declare function buildActionUrl(publicUrl: string, token: string): string;
+//# sourceMappingURL=tokens.d.ts.map

package/dist/approvals/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/approvals/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAA;AAE7E,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,iBAAiB,CAAA;IACzB,UAAU,EAAE,MAAM,CAAA;IAClB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,CAAA;CACjB;AA2BD;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,CAAC,CAKjB;AAED,MAAM,WAAW,aAAa;IAC5B,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,GAChC;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAA;AAEhC;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAiDvB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGvE"}

package/dist/approvals/tokens.js

@@ -0,0 +1,123 @@
+/**
+ * HMAC-signed action tokens used in inline action emails (Approve / Decline /
+ * Request changes / Discuss). Each token is bound to one approval, one
+ * action, and one approver. Tokens are valid for a configurable window
+ * (default 14 days) and consumed via the `consumedTokens` array on the
+ * approval record so they can't be replayed.
+ *
+ * Crypto uses the Web Crypto API (`crypto.subtle`) so the same code runs
+ * in Node and edge runtimes.
+ */
+/**
+ * How long an emailed action link stays usable.
+ *
+ * Was fourteen days, which outlived the thing the link acts on: `plugin.ts`
+ * expires an approval request after seven (`expirationDays ?? 7`), so the
+ * second week of a token's life could only ever act on something already gone.
+ *
+ * Seventy-two hours is what an approval actually needs. It covers a weekend,
+ * which is the realistic gap between sending a request and somebody opening
+ * their mail, and it is well inside the request's own expiry so the two cannot
+ * disagree. `createExpireStaleApprovalsFunction` handles anything that ages
+ * out either way.
+ *
+ * The token is otherwise well built — HMAC-SHA256, constant-time compare, bound
+ * to one approval, action and approver, single-use, with a confirmation
+ * interstitial — so this is narrowing a window rather than closing a hole.
+ * forumone/forumone-2026#486, F-13.
+ *
+ * Overridable per call through `maxAgeMs`, which is unchanged.
+ */
+const DEFAULT_MAX_AGE_MS = 72 * 60 * 60 * 1000;
+const TOKEN_PARTS = 5;
+const VALID_ACTIONS = new Set(['approve', 'decline', 'changes', 'discuss']);
+const ENCODER = new TextEncoder();
+/**
+ * Mints an action token. Returns a base64url-encoded payload with the
+ * format `<approvalId>:<action>:<approverId>:<issuedAt>:<signature>`.
+ */
+export async function generateActionToken(token, secret) {
+    ensureSafeForEncoding(token);
+    const payload = `${token.approvalId}:${token.action}:${token.approverId}:${token.issuedAt}`;
+    const signature = await hmacSignHex(payload, secret);
+    return base64UrlEncode(`${payload}:${signature}`);
+}
+/**
+ * Verifies a base64url-encoded action token with constant-time signature
+ * comparison. Returns either the parsed token or a structured error.
+ */
+export async function verifyActionToken(encoded, secret, options = {}) {
+    let decoded;
+    try {
+        decoded = base64UrlDecode(encoded);
+    }
+    catch {
+        return { ok: false, error: 'Token decode failed' };
+    }
+    const parts = decoded.split(':');
+    if (parts.length !== TOKEN_PARTS)
+        return { ok: false, error: 'Invalid token format' };
+    const [approvalId, action, approverId, issuedAtRaw, providedSignature] = parts;
+    if (!approvalId || !action || !approverId || !issuedAtRaw || !providedSignature) {
+        return { ok: false, error: 'Invalid token format' };
+    }
+    const issuedAt = Number.parseInt(issuedAtRaw, 10);
+    if (!Number.isFinite(issuedAt)) {
+        return { ok: false, error: 'Invalid token timestamp' };
+    }
+    if (!VALID_ACTIONS.has(action)) {
+        return { ok: false, error: 'Invalid action' };
+    }
+    const expectedSignature = await hmacSignHex(`${approvalId}:${action}:${approverId}:${issuedAt}`, secret);
+    if (!constantTimeEqual(providedSignature, expectedSignature)) {
+        return { ok: false, error: 'Invalid token signature' };
+    }
+    const maxAge = options.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+    const now = options.now ?? Date.now();
+    if (now - issuedAt > maxAge) {
+        return { ok: false, error: 'Token has expired' };
+    }
+    return {
+        ok: true,
+        token: { approvalId, action: action, approverId, issuedAt },
+    };
+}
+/**
+ * Returns the absolute URL an approver visits to invoke the action. The
+ * server-side endpoint (added by the plugin) verifies the token and
+ * presents a confirmation page before recording the decision.
+ */
+export function buildActionUrl(publicUrl, token) {
+    const base = publicUrl.replace(/\/$/, '');
+    return `${base}/api/approvals/action?token=${encodeURIComponent(token)}`;
+}
+async function hmacSignHex(payload, secret) {
+    const key = await crypto.subtle.importKey('raw', ENCODER.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const signature = await crypto.subtle.sign('HMAC', key, ENCODER.encode(payload));
+    return Array.from(new Uint8Array(signature))
+        .map((b) => b.toString(16).padStart(2, '0'))
+        .join('');
+}
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return result === 0;
+}
+function ensureSafeForEncoding(token) {
+    if (token.approvalId.includes(':') ||
+        token.approverId.includes(':') ||
+        token.action.includes(':')) {
+        throw new Error('Token field contains a reserved colon character');
+    }
+}
+function base64UrlEncode(input) {
+    return Buffer.from(input, 'utf-8').toString('base64url');
+}
+function base64UrlDecode(encoded) {
+    return Buffer.from(encoded, 'base64url').toString('utf-8');
+}
+//# sourceMappingURL=tokens.js.map

package/dist/approvals/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../../src/approvals/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAYH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,kBAAkB,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAA;AAC9C,MAAM,WAAW,GAAG,CAAC,CAAA;AACrB,MAAM,aAAa,GAAG,IAAI,GAAG,CAAoB,CAAC,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAA;AAC9F,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAA;AAEjC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,KAAkB,EAClB,MAAc;IAEd,qBAAqB,CAAC,KAAK,CAAC,CAAA;IAC5B,MAAM,OAAO,GAAG,GAAG,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,UAAU,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAA;IAC3F,MAAM,SAAS,GAAG,MAAM,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;IACpD,OAAO,eAAe,CAAC,GAAG,OAAO,IAAI,SAAS,EAAE,CAAC,CAAA;AACnD,CAAC;AAaD;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAe,EACf,MAAc,EACd,UAAyB,EAAE;IAE3B,IAAI,OAAe,CAAA;IACnB,IAAI,CAAC;QACH,OAAO,GAAG,eAAe,CAAC,OAAO,CAAC,CAAA;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAA;IACpD,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAA;IAChC,IAAI,KAAK,CAAC,MAAM,KAAK,WAAW;QAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,sBAAsB,EAAE,CAAA;IAErF,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,iBAAiB,CAAC,GAAG,KAMxE,CAAA;IACD,IAAI,CAAC,UAAU,IAAI,CAAC,MAAM,IAAI,CAAC,UAAU,IAAI,CAAC,WAAW,IAAI,CAAC,iBAAiB,EAAE,CAAC;QAChF,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,sBAAsB,EAAE,CAAA;IACrD,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,EAAE,CAAC,CAAA;IACjD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC/B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,yBAAyB,EAAE,CAAA;IACxD,CAAC;IAED,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,MAA2B,CAAC,EAAE,CAAC;QACpD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,EAAE,CAAA;IAC/C,CAAC;IAED,MAAM,iBAAiB,GAAG,MAAM,WAAW,CACzC,GAAG,UAAU,IAAI,MAAM,IAAI,UAAU,IAAI,QAAQ,EAAE,EACnD,MAAM,CACP,CAAA;IACD,IAAI,CAAC,iBAAiB,CAAC,iBAAiB,EAAE,iBAAiB,CAAC,EAAE,CAAC;QAC7D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,yBAAyB,EAAE,CAAA;IACxD,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,IAAI,kBAAkB,CAAA;IACrD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,EAAE,CAAA;IACrC,IAAI,GAAG,GAAG,QAAQ,GAAG,MAAM,EAAE,CAAC;QAC5B,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAA;IAClD,CAAC;IAED,OAAO;QACL,EAAE,EAAE,IAAI;QACR,KAAK,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,MAA2B,EAAE,UAAU,EAAE,QAAQ,EAAE;KACjF,CAAA;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE,KAAa;IAC7D,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAA;IACzC,OAAO,GAAG,IAAI,+BAA+B,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAA;AAC1E,CAAC;AAED,KAAK,UAAU,WAAW,CAAC,OAAe,EAAE,MAAc;IACxD,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,SAAS,CACvC,KAAK,EACL,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,EACtB,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,EACjC,KAAK,EACL,CAAC,MAAM,CAAC,CACT,CAAA;IACD,MAAM,SAAS,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAA;IAChF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,UAAU,CAAC,SAAS,CAAC,CAAC;SACzC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SAC3C,IAAI,CAAC,EAAE,CAAC,CAAA;AACb,CAAC;AAED,SAAS,iBAAiB,CAAC,CAAS,EAAE,CAAS;IAC7C,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IACvC,IAAI,MAAM,GAAG,CAAC,CAAA;IACd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,MAAM,IAAI,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;IAC7C,CAAC;IACD,OAAO,MAAM,KAAK,CAAC,CAAA;AACrB,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAkB;IAC/C,IACE,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC;QAC9B,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC;QAC9B,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,EAC1B,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAA;IACpE,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAA;AAC1D,CAAC;AAED,SAAS,eAAe,CAAC,OAAe;IACtC,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAA;AAC5D,CAAC"}

package/dist/approvals/tools/descriptors.d.ts

@@ -0,0 +1,26 @@
+import type { McpToolDescriptor } from '../../mcp/collector.js';
+export declare const APPROVALS_TOOLS: {
+    readonly requestApproval: {
+        readonly name: "request_approval";
+        readonly description: "Kicks off the approval workflow for a document that requires approval before publishing. Provide a clear changesSummary explaining what changed and why; approvers see this in their notifications. Returns the approval ID, expiration time, and the list of approvers who were notified.";
+    };
+    readonly respondToApproval: {
+        readonly name: "respond_to_approval";
+        readonly description: "Records an approver's decision on a pending approval. Valid decisions: approve, decline, request_changes. Approvers can also act through the inline action links in their notification emails; this tool is for when they respond conversationally through Claude.";
+    };
+    readonly getApprovalStatus: {
+        readonly name: "get_approval_status";
+        readonly description: "Returns the current status of an approval request including who decided, when, and any notes. Read-only; no audit record is written.";
+    };
+    readonly listPendingApprovals: {
+        readonly name: "list_pending_approvals";
+        readonly description: "Returns pending approval requests routed to one of the caller's approver groups. Use to answer 'what do I need to review?'. Read-only.";
+    };
+    readonly listMyRequests: {
+        readonly name: "list_my_requests";
+        readonly description: "Returns approval requests the current user has submitted, optionally filtered by status. Use to answer 'what's the state of my pending approvals?'. Read-only.";
+    };
+};
+/** Every tool this server contributes, for the collector. */
+export declare const APPROVALS_TOOL_DESCRIPTORS: readonly McpToolDescriptor[];
+//# sourceMappingURL=descriptors.d.ts.map

package/dist/approvals/tools/descriptors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptors.d.ts","sourceRoot":"","sources":["../../../src/approvals/tools/descriptors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAY/D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;CA0B0B,CAAA;AAEtD,6DAA6D;AAC7D,eAAO,MAAM,0BAA0B,EAAE,SAAS,iBAAiB,EACnC,CAAA"}

package/dist/approvals/tools/descriptors.js

@@ -0,0 +1,35 @@
+/*
+This server's tools, by name and description, knowable without a Payload.
+
+`@payloadcms/plugin-mcp` reads exactly these two fields while the host's config
+is being built, to generate one per-key checkbox per tool, and denies any tool it
+has no checkbox for. The handlers close over `payload` and the audit writer, so
+they cannot exist that early — the names never needed to wait for them.
+
+The factories below spread these, so the two cannot drift.
+*/
+export const APPROVALS_TOOLS = {
+    requestApproval: {
+        name: 'request_approval',
+        description: 'Kicks off the approval workflow for a document that requires approval before publishing. Provide a clear changesSummary explaining what changed and why; approvers see this in their notifications. Returns the approval ID, expiration time, and the list of approvers who were notified.',
+    },
+    respondToApproval: {
+        name: 'respond_to_approval',
+        description: "Records an approver's decision on a pending approval. Valid decisions: approve, decline, request_changes. Approvers can also act through the inline action links in their notification emails; this tool is for when they respond conversationally through Claude.",
+    },
+    getApprovalStatus: {
+        name: 'get_approval_status',
+        description: 'Returns the current status of an approval request including who decided, when, and any notes. Read-only; no audit record is written.',
+    },
+    listPendingApprovals: {
+        name: 'list_pending_approvals',
+        description: "Returns pending approval requests routed to one of the caller's approver groups. Use to answer 'what do I need to review?'. Read-only.",
+    },
+    listMyRequests: {
+        name: 'list_my_requests',
+        description: "Returns approval requests the current user has submitted, optionally filtered by status. Use to answer 'what's the state of my pending approvals?'. Read-only.",
+    },
+};
+/** Every tool this server contributes, for the collector. */
+export const APPROVALS_TOOL_DESCRIPTORS = Object.values(APPROVALS_TOOLS);
+//# sourceMappingURL=descriptors.js.map

package/dist/approvals/tools/descriptors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptors.js","sourceRoot":"","sources":["../../../src/approvals/tools/descriptors.ts"],"names":[],"mappings":"AAEA;;;;;;;;;EASE;AACF,MAAM,CAAC,MAAM,eAAe,GAAG;IAC7B,eAAe,EAAE;QACf,IAAI,EAAE,kBAAkB;QACxB,WAAW,EACT,4RAA4R;KAC/R;IACD,iBAAiB,EAAE;QACjB,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EACT,oQAAoQ;KACvQ;IACD,iBAAiB,EAAE;QACjB,IAAI,EAAE,qBAAqB;QAC3B,WAAW,EACT,sIAAsI;KACzI;IACD,oBAAoB,EAAE;QACpB,IAAI,EAAE,wBAAwB;QAC9B,WAAW,EACT,wIAAwI;KAC3I;IACD,cAAc,EAAE;QACd,IAAI,EAAE,kBAAkB;QACxB,WAAW,EACT,gKAAgK;KACnK;CACmD,CAAA;AAEtD,6DAA6D;AAC7D,MAAM,CAAC,MAAM,0BAA0B,GACrC,MAAM,CAAC,MAAM,CAAC,eAAe,CAAC,CAAA"}

package/dist/approvals/tools/get-approval-status.d.ts

@@ -0,0 +1,11 @@
+import type { Payload } from 'payload';
+import type { McpToolDefinition } from '../../plugin-contract/mcp.js';
+import type { ApprovalsPluginOptions } from '../options.js';
+export interface GetApprovalStatusDeps {
+    payload: Payload;
+    options: ApprovalsPluginOptions & {
+        tokenSecret: string;
+    };
+}
+export declare function createGetApprovalStatusTool(deps: GetApprovalStatusDeps): McpToolDefinition;
+//# sourceMappingURL=get-approval-status.d.ts.map

package/dist/approvals/tools/get-approval-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-approval-status.d.ts","sourceRoot":"","sources":["../../../src/approvals/tools/get-approval-status.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AAGtC,OAAO,KAAK,EAAkB,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AAErF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAA;AAG3D,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,OAAO,CAAA;IAChB,OAAO,EAAE,sBAAsB,GAAG;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAA;CAC1D;AAqDD,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,qBAAqB,GAAG,iBAAiB,CA2C1F"}

package/dist/approvals/tools/get-approval-status.js

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+import { unwrapRelationshipId } from '../../utils/relationships.js';
+import { withMeta } from '../../mcp/meta.js';
+import { DEFAULT_APPROVALS_SLUG } from '../collection.js';
+import { APPROVALS_TOOLS } from './descriptors.js';
+/*
+Who may read one approval by id.
+
+Audit 04 F-20. This handler was `async (input) =>` — the signature did not
+accept `ctx` at all, so there was nothing to check against and nothing was
+checked. It `findByID`s an arbitrary `approvalId` at the Local API default of
+`overrideAccess: true` and returns the target, the requester, the approver
+groups, the decision and the decision notes.
+
+The other four tools on this server all refuse an unauthenticated caller. This
+was the one that still answered when they denied, and that asymmetry is not
+theoretical: `@payloadcms/plugin-mcp` never assigns `req.user`, so for a
+`Bearer`-authenticated MCP call `ctx.user` is null and the refusal below is the
+branch that actually fires today.
+
+## The rule is the union of the two list tools, and deliberately nothing more
+
+`list_my_requests` shows a caller the approvals they requested.
+`list_pending_approvals` shows a caller the approvals routed to one of their
+groups. Between them they already disclose every field this tool returns. So
+the rule here is *requester or approver-group member*, which makes the by-id
+read agree with the by-list reads rather than being a way around them.
+
+No admin bypass, because `respond_to_approval` has none either and a second
+policy on the same collection is how the two drift. An admin who needs an
+arbitrary approval has the admin UI and the REST collection, both of which
+apply `approval-requests`' own access rules — which is the thing this server
+should not be quietly wider than.
+
+The order of the three checks is load-bearing. Identity first, because the
+unauthenticated refusal must not depend on the id existing; then the document;
+then membership.
+*/
+/**
+ * Whether this caller is a party to this approval.
+ *
+ * Group membership is compared exactly as `respond_to_approval` compares it —
+ * `approverGroups` against `ctx.user.groups`, slug by slug — so a change in how
+ * groups are named breaks both together rather than leaving this one behind.
+ */
+function isPartyTo(approval, user) {
+    if (unwrapRelationshipId(approval['requestedBy']) === user.id)
+        return true;
+    const approverGroups = approval['approverGroups'] ?? [];
+    return approverGroups.some((group) => user.groups.includes(group));
+}
+export function createGetApprovalStatusTool(deps) {
+    const inputSchema = withMeta({
+        approvalId: z.string(),
+    });
+    return {
+        ...APPROVALS_TOOLS.getApprovalStatus,
+        inputSchema,
+        handler: async (input, ctx) => {
+            if (!ctx.user) {
+                return { error: 'Must be authenticated to read an approval request' };
+            }
+            const approval = (await deps.payload.findByID({
+                collection: deps.options.collectionSlug ?? DEFAULT_APPROVALS_SLUG,
+                id: input.approvalId,
+            }));
+            if (!approval)
+                return { error: 'Approval not found' };
+            /*
+            The same sentence as "not found", and that is the point: a caller who is
+            not a party to this request learns nothing about whether the id names one.
+            Ids are sequential, so a distinguishable refusal enumerates the collection.
+            */
+            if (!isPartyTo(approval, ctx.user))
+                return { error: 'Approval not found' };
+            return {
+                approvalId: String(approval['id']),
+                status: approval['status'],
+                targetCollection: approval['targetCollection'],
+                targetId: approval['targetId'],
+                targetTitle: approval['targetTitle'],
+                targetVersion: approval['targetVersion'],
+                requestedBy: unwrapRelationshipId(approval['requestedBy']),
+                requestedAt: approval['requestedAt'],
+                approverGroups: approval['approverGroups'],
+                decidedBy: unwrapRelationshipId(approval['decidedBy']),
+                decidedAt: approval['decidedAt'],
+                decisionNotes: approval['decisionNotes'],
+                expiresAt: approval['expiresAt'],
+            };
+        },
+    };
+}
+//# sourceMappingURL=get-approval-status.js.map

package/dist/approvals/tools/get-approval-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-approval-status.js","sourceRoot":"","sources":["../../../src/approvals/tools/get-approval-status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAA;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAA;AAE5C,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAA;AAEzD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAOlD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgCE;AAEF;;;;;;GAMG;AACH,SAAS,SAAS,CAChB,QAAiC,EACjC,IAAyC;IAEzC,IAAI,oBAAoB,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,KAAK,IAAI,CAAC,EAAE;QAAE,OAAO,IAAI,CAAA;IAE1E,MAAM,cAAc,GAAI,QAAQ,CAAC,gBAAgB,CAA0B,IAAI,EAAE,CAAA;IACjF,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAA;AACpE,CAAC;AAED,MAAM,UAAU,2BAA2B,CAAC,IAA2B;IACrE,MAAM,WAAW,GAAG,QAAQ,CAAC;QAC3B,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;KACvB,CAAC,CAAA;IAEF,OAAO;QACL,GAAG,eAAe,CAAC,iBAAiB;QACpC,WAAW;QACX,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE;YAC5B,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;gBACd,OAAO,EAAE,KAAK,EAAE,mDAAmD,EAAE,CAAA;YACvE,CAAC;YAED,MAAM,QAAQ,GAAG,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC;gBAC5C,UAAU,EAAE,IAAI,CAAC,OAAO,CAAC,cAAc,IAAI,sBAAsB;gBACjE,EAAE,EAAE,KAAK,CAAC,UAAU;aACrB,CAAC,CAAmC,CAAA;YACrC,IAAI,CAAC,QAAQ;gBAAE,OAAO,EAAE,KAAK,EAAE,oBAAoB,EAAE,CAAA;YAErD;;;;cAIE;YACF,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,GAAG,CAAC,IAAI,CAAC;gBAAE,OAAO,EAAE,KAAK,EAAE,oBAAoB,EAAE,CAAA;YAE1E,OAAO;gBACL,UAAU,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;gBAClC,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC;gBAC1B,gBAAgB,EAAE,QAAQ,CAAC,kBAAkB,CAAC;gBAC9C,QAAQ,EAAE,QAAQ,CAAC,UAAU,CAAC;gBAC9B,WAAW,EAAE,QAAQ,CAAC,aAAa,CAAC;gBACpC,aAAa,EAAE,QAAQ,CAAC,eAAe,CAAC;gBACxC,WAAW,EAAE,oBAAoB,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC;gBAC1D,WAAW,EAAE,QAAQ,CAAC,aAAa,CAAC;gBACpC,cAAc,EAAE,QAAQ,CAAC,gBAAgB,CAAC;gBAC1C,SAAS,EAAE,oBAAoB,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;gBACtD,SAAS,EAAE,QAAQ,CAAC,WAAW,CAAC;gBAChC,aAAa,EAAE,QAAQ,CAAC,eAAe,CAAC;gBACxC,SAAS,EAAE,QAAQ,CAAC,WAAW,CAAC;aACjC,CAAA;QACH,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/approvals/tools/index.d.ts

@@ -0,0 +1,7 @@
+export { APPROVALS_TOOLS, APPROVALS_TOOL_DESCRIPTORS } from './descriptors.js';
+export { createRequestApprovalTool, type RequestApprovalDeps, } from './request-approval.js';
+export { createRespondToApprovalTool, type RespondToApprovalDeps, } from './respond-to-approval.js';
+export { createGetApprovalStatusTool, type GetApprovalStatusDeps, } from './get-approval-status.js';
+export { createListPendingApprovalsTool, type ListPendingApprovalsDeps, } from './list-pending-approvals.js';
+export { createListMyRequestsTool, type ListMyRequestsDeps, } from './list-my-requests.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/approvals/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/approvals/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAA;AAC9E,OAAO,EACL,yBAAyB,EACzB,KAAK,mBAAmB,GACzB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACL,2BAA2B,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,2BAA2B,EAC3B,KAAK,qBAAqB,GAC3B,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,8BAA8B,EAC9B,KAAK,wBAAwB,GAC9B,MAAM,6BAA6B,CAAA;AACpC,OAAO,EACL,wBAAwB,EACxB,KAAK,kBAAkB,GACxB,MAAM,uBAAuB,CAAA"}

package/dist/approvals/tools/index.js

@@ -0,0 +1,7 @@
+export { APPROVALS_TOOLS, APPROVALS_TOOL_DESCRIPTORS } from './descriptors.js';
+export { createRequestApprovalTool, } from './request-approval.js';
+export { createRespondToApprovalTool, } from './respond-to-approval.js';
+export { createGetApprovalStatusTool, } from './get-approval-status.js';
+export { createListPendingApprovalsTool, } from './list-pending-approvals.js';
+export { createListMyRequestsTool, } from './list-my-requests.js';
+//# sourceMappingURL=index.js.map

package/dist/approvals/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/approvals/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAA;AAC9E,OAAO,EACL,yBAAyB,GAE1B,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACL,2BAA2B,GAE5B,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,2BAA2B,GAE5B,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,8BAA8B,GAE/B,MAAM,6BAA6B,CAAA;AACpC,OAAO,EACL,wBAAwB,GAEzB,MAAM,uBAAuB,CAAA"}

package/dist/approvals/tools/list-my-requests.d.ts

@@ -0,0 +1,11 @@
+import type { Payload } from 'payload';
+import type { McpToolDefinition } from '../../plugin-contract/mcp.js';
+import type { ApprovalsPluginOptions } from '../options.js';
+export interface ListMyRequestsDeps {
+    payload: Payload;
+    options: ApprovalsPluginOptions & {
+        tokenSecret: string;
+    };
+}
+export declare function createListMyRequestsTool(deps: ListMyRequestsDeps): McpToolDefinition;
+//# sourceMappingURL=list-my-requests.d.ts.map