@advertising-chat/mcp 0.2.1 → 0.17.3

package/bin/tools/decisions.js

@@ -0,0 +1,309 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decisionTools = exports.getStats = exports.findRequests = exports.explainDecision = exports.REASON_MEANINGS = exports.OUTCOME_MEANINGS = exports.STAGE_MEANINGS = void 0;
+exports.explainTrace = explainTrace;
+exports.journalRow = journalRow;
+/**
+ * Decisions and results: why a request returned what it did, an agent's
+ * recent requests, and an entity's event counts.
+ *
+ * `explain_decision` calls the gateway's decision-trace route (ads reads the
+ * trace from BigQuery, filtered by the caller's org, so another org's message
+ * is a 404). The trace speaks the API's names (ad unit, line item, creative);
+ * the tool reshapes it into the console's (moment, audience, offer, customer details)
+ * and drops the scoring internals a model does not need to explain an
+ * outcome. `find_requests` reads the fetch journal (`/offer-manager/journal`:
+ * seven days, org scoped, newest first, at most 500 rows); every journaled
+ * request carries the message id `explain_decision` takes.
+ */
+const zod_1 = require("zod");
+const client_1 = require("../client");
+const tool_1 = require("../tool");
+const shared_1 = require("./shared");
+/** Plain meanings of the pipeline stages, in pipeline order. */
+exports.STAGE_MEANINGS = {
+    sourcing: "Collected the moment's offers that are on (their audiences) and its ads from the network",
+    eligibility: "Each audience's limit (maximum impressions or target fill rate)",
+    channel: "Each audience's channels against the request's channel (the channel parameter, or the format)",
+    schedule: "Each audience's schedule (dates, days, hours) in the org time zone",
+    ruleTargeting: "Each audience's Who sees it and Who doesn’t, per offer, against the attributes the agent sent and the customer's offer history",
+    formatEligibility: 'Whether the audience has an offer that can render in the requested format',
+    fallbackReflow: 'Fallback audiences considered because no other qualified',
+    frequencyCaps: "The workspace's offer limit (how many of the brand's offers one customer may see in a period; ads from the network are not limited), then each audience's How often (at most times serves per interval)",
+    semanticRelevance: 'Relevance of each offer to the conversation the agent sent',
+    appropriatenessGate: 'Whether any offer is appropriate in this moment of the conversation',
+    scoring: 'Priority, then a weighted draw within the top priority',
+    render: 'Rendering the chosen offer for the channel',
+};
+/** Plain meanings of the request outcomes (ads `ErrorResponse` reasons). */
+exports.OUTCOME_MEANINGS = {
+    filled: 'An offer was returned.',
+    UnknownAdUnit: 'The moment code the agent sent does not exist.',
+    AdUnitDisabled: 'The moment is disabled.',
+    NoLineItemsConfigured: 'No offer that is on (published) is set to show at this moment, and ads from the network are off there.',
+    OfferLimitReached: "The customer had reached the workspace's offer limit, and no ad from the network qualified.",
+    NoEligibleLineItems: 'Nothing qualified: each audience was removed by a limit, its channels, its schedule, its audience or exclusions, or format.',
+    LineItemLimitExceeded: 'The customer had reached the How often cap of every qualifying audience.',
+    NoAdAvailable: 'The chosen audiences produced nothing to show: the network returned no ad, or no offer could render.',
+    'appropriateness-gate': 'The conversation was judged a poor moment for any offer, so none was shown.',
+    UnsupportedFormat: 'The agent asked for a render format that is not supported.',
+    MissingRequiredParameter: 'The request was missing a required parameter.',
+    InvalidParameterValue: 'The request had an invalid parameter value.',
+    'internal-error': 'The request failed with an internal error.',
+};
+const PRIORITY = {
+    6: 'High',
+    8: 'Default',
+    10: 'Low',
+    12: 'Network',
+};
+const STATUS = {
+    won: 'shown',
+    eliminated: 'removed',
+    'lost-auction': 'chosen but could not serve an offer',
+    unused: 'qualified, another was chosen',
+    'not-considered': 'fallback, not needed',
+};
+/** Plain meanings of the ads elimination reason codes. */
+exports.REASON_MEANINGS = {
+    limit: "The audience's delivery limit",
+    channel: "The request's channel is not one of the audience's channels, or the request named none",
+    schedule: "Outside the audience's schedule",
+    audience: 'The customer does not match Who sees it',
+    exclusions: 'The customer matches Who doesn’t see it',
+    format: 'No offer of the audience can render in the requested format',
+    offer_limit: "The customer reached the workspace's offer limit (these are the brand's own offers)",
+    frequency: "The customer reached the audience's How often",
+};
+/** The trace record (ads `DecisionTraceRecord`) in Offer Manager terms. */
+function explainTrace(record) {
+    const t = record.trace ?? {};
+    const req = t.request ?? {};
+    const attributes = {};
+    for (const kv of Array.isArray(req.targeting) ? req.targeting : []) {
+        if (kv && typeof kv.key === 'string')
+            attributes[kv.key] = kv.value;
+    }
+    const outcome = record.outcome ?? t.outcome ?? 'unknown';
+    const winner = t.winner ?? null;
+    const stages = Array.isArray(t.stages) ? t.stages : [];
+    return {
+        messageId: record.messageId,
+        at: record.timestamp ?? t.timestamp,
+        outcome,
+        meaning: exports.OUTCOME_MEANINGS[outcome] ?? 'No offer was returned.',
+        request: {
+            moment: {
+                code: req.adUnitCode ?? record.adUnitCode,
+                id: req.adUnit ?? record.adUnit,
+            },
+            agent: req.application ?? undefined,
+            subscriber: req.subscriber ?? record.subscriber ?? undefined,
+            format: req.format ?? record.requestFormat,
+            channel: req.channel
+                ? { channel: req.channel, from: req.channelSource }
+                : 'not known (no channel parameter, and the format names none)',
+            evaluatedAt: req.evaluatedAt ?? undefined,
+            timeZone: req.timeZone ?? undefined,
+            attributes,
+            conversationContext: t.context
+                ? {
+                    sent: !!t.context.provided,
+                    ignored: !!t.context.ignored || undefined,
+                    truncated: !!t.context.truncated || undefined,
+                }
+                : undefined,
+        },
+        shown: winner
+            ? { audience: winner.lineItem, offer: winner.creatives?.[0] ?? null }
+            : null,
+        audiences: (Array.isArray(t.candidates) ? t.candidates : []).map((c) => ({
+            id: c.id,
+            name: c.name,
+            priority: PRIORITY[c.priority] ?? c.priority,
+            fallback: c.fallback || undefined,
+            result: STATUS[c.status] ?? c.status,
+            removedAt: c.eliminatedBy
+                ? `${c.eliminatedBy}: ${exports.STAGE_MEANINGS[c.eliminatedBy] ?? ''}`.trim()
+                : undefined,
+            reason: c.reason,
+            why: c.reasonCode
+                ? (exports.REASON_MEANINGS[c.reasonCode] ?? c.reasonCode)
+                : undefined,
+            decidingCondition: c.condition,
+            offersExcluded: Array.isArray(c.offersExcluded)
+                ? c.offersExcluded.map((o) => ({
+                    offer: o.offer,
+                    why: exports.REASON_MEANINGS[o.reasonCode] ?? o.reasonCode,
+                    reason: o.reason,
+                }))
+                : undefined,
+        })),
+        stages: stages.map(s => ({
+            stage: s.name,
+            checks: exports.STAGE_MEANINGS[s.name],
+            status: s.status,
+            audiencesIn: s.candidatesIn,
+            audiencesOut: s.candidatesOut,
+            ...(s.name === 'appropriatenessGate' && s.detail
+                ? { detail: s.detail }
+                : {}),
+        })),
+    };
+}
+const NOT_FOUND_NOTE = 'No decision trace for this message in this org. Possible reasons: the id is mistyped or belongs to another org; the request was a test (test requests are not traced; their response lists the disqualifications instead); the request was made in the last minute and the trace has not arrived yet; or it is older than 90 days.';
+exports.explainDecision = (0, tool_1.defineTool)({
+    name: 'explain_decision',
+    title: 'Explain a decision',
+    description: 'Why an offer request returned the offer it did, or none: the moment and attributes the agent sent, every audience considered (a rule; the console calls it the offer’s audience, or for an agent’s ads from the network its network setting) with whether it was shown or why it was removed, and the pipeline stages. Takes either the message id of one request (`messageId` in the fetch response, or the X-Adchat-Message-Id header of an empty one; starts with "direqt-"), which the agent logs, find_requests returns, and the request log on the agent’s Connect tab in the console shows; or a customer id (`subscriber`, the id the agent sends) for that customer’s latest requests, at most 10, newest first. Live requests only, kept 90 days. Maps to GET /system/offer-manager/decision-trace/{messageId} and GET /system/offer-manager/decision-trace?subscriber={subscriber}.',
+    kind: 'read',
+    roleFloor: 'viewer',
+    input: {
+        messageId: zod_1.z
+            .string()
+            .min(1)
+            .optional()
+            .describe('The fetch response messageId, for example "direqt-5f0c…"'),
+        subscriber: zod_1.z
+            .string()
+            .min(1)
+            .optional()
+            .describe('A customer id the agent sends, for that customer’s latest requests. Pass this or messageId.'),
+    },
+    async run({ client }, { messageId, subscriber }) {
+        const customer = subscriber?.trim();
+        if (!messageId?.trim() && customer) {
+            const { traces } = await client.get(`${shared_1.OM}/decision-trace?subscriber=${(0, shared_1.enc)(customer)}`);
+            const list = Array.isArray(traces) ? traces : [];
+            return list.length
+                ? { subscriber: customer, requests: list.map(explainTrace) }
+                : {
+                    found: false,
+                    subscriber: customer,
+                    note: 'No decision traces for this customer in this org in the last 90 days. The id may be mistyped, the agent may send a different id for them, or their requests were tests (not traced).',
+                };
+        }
+        const id = messageId?.trim() ?? '';
+        if (!id.startsWith('direqt-'))
+            return {
+                found: false,
+                messageId: id,
+                note: 'A message id starts with "direqt-". Ask the user for the messageId from the fetch response or the request log, or for the customer id the agent sends.',
+            };
+        try {
+            const record = await client.get(`${shared_1.OM}/decision-trace/${(0, shared_1.enc)(id)}`);
+            return explainTrace(record);
+        }
+        catch (err) {
+            if (err instanceof client_1.ApiError && err.status === 404)
+                return { found: false, messageId: id, note: NOT_FOUND_NOTE };
+            throw err;
+        }
+    },
+});
+const HOUR_MS = 60 * 60 * 1000;
+function journalRow(j) {
+    const attributes = {};
+    for (const kv of Array.isArray(j.requestTargeting)
+        ? j.requestTargeting
+        : []) {
+        if (kv && typeof kv.key === 'string')
+            attributes[kv.key] = kv.value;
+    }
+    const reason = j.errorResponse?.reason;
+    const offer = Array.isArray(j.creatives) ? j.creatives[0] : undefined;
+    return {
+        at: j.timestamp,
+        agent: typeof j.application === 'string' ? j.application : undefined,
+        moment: j.requestAdUnit,
+        subscriber: j.requestSubscriberId || undefined,
+        attributes,
+        result: reason
+            ? { offer: null, reason, meaning: exports.OUTCOME_MEANINGS[reason] }
+            : {
+                audience: j.lineItem?.name,
+                offer: offer?.name ?? null,
+            },
+        messageId: j.messageId || undefined,
+    };
+}
+exports.findRequests = (0, tool_1.defineTool)({
+    name: 'find_requests',
+    title: 'Find offer requests',
+    description: 'Recent live offer requests from the fetch journal (kept 7 days), newest first: when, the agent, the moment code, the subscriber id, the attributes the agent sent, the result (the audience and offer shown, or the reason none was), and the messageId to pass to explain_decision. Filter by `application` (agent), `subscriber` (the customer id the agent sends), and `moment` (a moment code from list_moments). Maps to GET /system/offer-manager/journal.',
+    kind: 'read',
+    roleFloor: 'viewer',
+    input: {
+        application: shared_1.application.optional(),
+        subscriber: zod_1.z
+            .string()
+            .optional()
+            .describe('Subscriber id the agent sends for the customer'),
+        moment: zod_1.z.string().optional().describe('Moment code, from list_moments'),
+        hours: zod_1.z
+            .number()
+            .int()
+            .min(1)
+            .max(168)
+            .optional()
+            .describe('How far back to look, in hours. Default 24, at most 168'),
+        limit: zod_1.z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .describe('Most rows to return. Default 20'),
+    },
+    async run({ client }, { application, subscriber, moment, hours, limit }) {
+        const now = Date.now();
+        const body = await client.get(`${shared_1.OM}/journal`, {
+            applications: application,
+            start: now - (hours ?? 24) * HOUR_MS,
+            end: now + HOUR_MS,
+            operations: 'Fetch',
+            subscribers: subscriber?.trim() || undefined,
+            moments: moment?.trim() || undefined,
+        });
+        const rows = Array.isArray(body) ? body : [];
+        const max = limit ?? 20;
+        return {
+            requests: rows.slice(0, max).map(journalRow),
+            total: rows.length,
+            more: rows.length > max || undefined,
+        };
+    },
+});
+const ENTITY = {
+    moment: 'adUnit',
+    rule: 'lineItem',
+    offer: 'creative',
+};
+exports.getStats = (0, tool_1.defineTool)({
+    name: 'get_stats',
+    title: 'Event counts for a moment, rule, or offer',
+    description: "Event counts for one moment, rule, or offer. `stat: 'sum'` totals every event type (fetches, impressions, clicks, conversions, responses), all time or over the last `hours`; `stat: 'fetch'` is per-minute requests over the last hour, a quick check that the agent is sending them. Maps to GET /system/offer-manager/event-stats/sum/{entity}/{id} and GET /system/offer-manager/event-stats/fetch/{entity}/{id}.",
+    kind: 'read',
+    roleFloor: 'viewer',
+    input: {
+        entity: zod_1.z.enum(['moment', 'rule', 'offer']),
+        id: (0, shared_1.id)('moment, rule, or offer'),
+        stat: zod_1.z.enum(['sum', 'fetch']),
+        hours: zod_1.z
+            .number()
+            .int()
+            .min(1)
+            .max(2160)
+            .optional()
+            .describe("For stat 'sum': the last this many hours. Default all time."),
+    },
+    async run({ client }, args) {
+        return client.get(`${shared_1.OM}/event-stats/${args.stat}/${ENTITY[args.entity]}/${(0, shared_1.enc)(args.id)}`, {
+            period: args.stat === 'sum' && args.hours
+                ? `last${args.hours}hours`
+                : undefined,
+        });
+    },
+});
+exports.decisionTools = [exports.findRequests, exports.explainDecision, exports.getStats];
+//# sourceMappingURL=decisions.js.map

package/bin/tools/decisions.js.map

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

package/bin/tools/docs.d.ts

@@ -0,0 +1,3 @@
+export declare const searchDocs: import("../tool").AnyTool;
+export declare const readDoc: import("../tool").AnyTool;
+export declare const docsTools: import("../tool").AnyTool[];

package/bin/tools/docs.js

@@ -0,0 +1,55 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.docsTools = exports.readDoc = exports.searchDocs = void 0;
+/**
+ * Docs tools: `search_docs` and `read_doc` over the public docs
+ * (docs.advertising.chat), ported from AnyChat. They read public pages and
+ * make no management API call.
+ */
+const zod_1 = require("zod");
+const tool_1 = require("../tool");
+exports.searchDocs = (0, tool_1.defineTool)({
+    name: 'search_docs',
+    title: 'Search the docs',
+    description: 'Keyword search over the Advertising.chat docs (docs.advertising.chat): how moments, offers, rules, conditions, How often and the offer limit, and fallback rules behave, console procedures, how agents request offers, and the API and rule reference. Returns matching pages with url, summary, and a snippet; follow up with read_doc. Use it for product questions instead of answering from memory.',
+    kind: 'read',
+    roleFloor: 'viewer',
+    input: {
+        query: zod_1.z
+            .string()
+            .min(2)
+            .describe('Keywords, for example "fallback rule offer limit"'),
+        limit: zod_1.z.number().int().min(1).max(20).optional().describe('Default 5'),
+    },
+    async run({ docs }, { query, limit }) {
+        const hits = await docs.search(query, limit ?? 5);
+        return hits.length
+            ? hits
+            : { hits: [], note: 'No matching pages. Try different keywords.' };
+    },
+});
+exports.readDoc = (0, tool_1.defineTool)({
+    name: 'read_doc',
+    title: 'Read a docs page',
+    description: 'The full markdown of one Advertising.chat docs page, by url (from search_docs) or by title, for example "Rule reference".',
+    kind: 'read',
+    roleFloor: 'viewer',
+    input: {
+        page: zod_1.z
+            .string()
+            .min(1)
+            .describe('Page url or title, for example "Moments, offers, and rules"'),
+    },
+    async run({ docs }, { page }) {
+        const doc = await docs.read(page);
+        if (!doc)
+            return {
+                error: `No docs page matches "${page}". Use search_docs to find the url.`,
+            };
+        // llms-full.txt bodies start with the page's own `# Title` line.
+        const body = doc.body?.replace(/^# [^\n]*\n+/, '');
+        return `# ${doc.title}\nSource: ${doc.url}\n\n${body ?? '(page body unavailable)'}`;
+    },
+});
+exports.docsTools = [exports.searchDocs, exports.readDoc];
+//# sourceMappingURL=docs.js.map

package/bin/tools/docs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs.js","sourceRoot":"","sources":["../../src/tools/docs.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,6BAAwB;AACxB,kCAAqC;AAExB,QAAA,UAAU,GAAG,IAAA,iBAAU,EAAC;IACnC,IAAI,EAAE,aAAa;IACnB,KAAK,EAAE,iBAAiB;IACxB,WAAW,EACT,0YAA0Y;IAC5Y,IAAI,EAAE,MAAM;IACZ,SAAS,EAAE,QAAQ;IACnB,KAAK,EAAE;QACL,KAAK,EAAE,OAAC;aACL,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,mDAAmD,CAAC;QAChE,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,WAAW,CAAC;KACxE;IACD,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;QAClC,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,IAAI,CAAC,CAAC,CAAC;QAClD,OAAO,IAAI,CAAC,MAAM;YAChB,CAAC,CAAC,IAAI;YACN,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,4CAA4C,EAAE,CAAC;IACvE,CAAC;CACF,CAAC,CAAC;AAEU,QAAA,OAAO,GAAG,IAAA,iBAAU,EAAC;IAChC,IAAI,EAAE,UAAU;IAChB,KAAK,EAAE,kBAAkB;IACzB,WAAW,EACT,2HAA2H;IAC7H,IAAI,EAAE,MAAM;IACZ,SAAS,EAAE,QAAQ;IACnB,KAAK,EAAE;QACL,IAAI,EAAE,OAAC;aACJ,MAAM,EAAE;aACR,GAAG,CAAC,CAAC,CAAC;aACN,QAAQ,CAAC,6DAA6D,CAAC;KAC3E;IACD,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE;QAC1B,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,GAAG;YACN,OAAO;gBACL,KAAK,EAAE,yBAAyB,IAAI,qCAAqC;aAC1E,CAAC;QACJ,iEAAiE;QACjE,MAAM,IAAI,GAAG,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC;QACnD,OAAO,KAAK,GAAG,CAAC,KAAK,aAAa,GAAG,CAAC,GAAG,OAAO,IAAI,IAAI,yBAAyB,EAAE,CAAC;IACtF,CAAC;CACF,CAAC,CAAC;AAEU,QAAA,SAAS,GAAG,CAAC,kBAAU,EAAE,eAAO,CAAC,CAAC"}

package/bin/tools/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The management tool table: every tool once, in a stable order (the
+ * order is the tool table hosts and the copilot send the model, so keep it
+ * stable for prompt caching).
+ */
+import type { AnyTool } from '../tool';
+export declare const allTools: AnyTool[];
+export declare const toolsByName: ReadonlyMap<string, AnyTool>;
+export * from './account';
+export * from './attributes';
+export * from './campaigns';
+export * from './decisions';
+export * from './docs';
+export * from './moments';
+export * from './network';
+export * from './offers';
+export * from './results';
+export * from './rules';
+export * from './settings';
+export * from './translation';
+export { ToolInputError } from './shared';

package/bin/tools/index.js

@@ -0,0 +1,60 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolInputError = exports.toolsByName = exports.allTools = void 0;
+const account_1 = require("./account");
+const attributes_1 = require("./attributes");
+const campaigns_1 = require("./campaigns");
+const decisions_1 = require("./decisions");
+const docs_1 = require("./docs");
+const moments_1 = require("./moments");
+const network_1 = require("./network");
+const offers_1 = require("./offers");
+const results_1 = require("./results");
+const rules_1 = require("./rules");
+const settings_1 = require("./settings");
+const translation_1 = require("./translation");
+exports.allTools = [
+    account_1.whoami,
+    account_1.listApplications,
+    ...moments_1.momentTools,
+    ...attributes_1.attributeTools,
+    ...translation_1.translationTools,
+    ...rules_1.ruleTools,
+    ...offers_1.offerTools,
+    ...results_1.resultsTools,
+    ...network_1.networkTools,
+    ...campaigns_1.campaignTools,
+    ...settings_1.settingsTools,
+    ...decisions_1.decisionTools,
+    ...docs_1.docsTools,
+];
+exports.toolsByName = new Map(exports.allTools.map(t => [t.name, t]));
+__exportStar(require("./account"), exports);
+__exportStar(require("./attributes"), exports);
+__exportStar(require("./campaigns"), exports);
+__exportStar(require("./decisions"), exports);
+__exportStar(require("./docs"), exports);
+__exportStar(require("./moments"), exports);
+__exportStar(require("./network"), exports);
+__exportStar(require("./offers"), exports);
+__exportStar(require("./results"), exports);
+__exportStar(require("./rules"), exports);
+__exportStar(require("./settings"), exports);
+__exportStar(require("./translation"), exports);
+var shared_1 = require("./shared");
+Object.defineProperty(exports, "ToolInputError", { enumerable: true, get: function () { return shared_1.ToolInputError; } });
+//# sourceMappingURL=index.js.map

package/bin/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAMA,uCAAqD;AACrD,6CAA8C;AAC9C,2CAA4C;AAC5C,2CAA4C;AAC5C,iCAAmC;AACnC,uCAAwC;AACxC,uCAAyC;AACzC,qCAAsC;AACtC,uCAAyC;AACzC,mCAAoC;AACpC,yCAA2C;AAC3C,+CAAiD;AAEpC,QAAA,QAAQ,GAAc;IACjC,gBAAM;IACN,0BAAgB;IAChB,GAAG,qBAAW;IACd,GAAG,2BAAc;IACjB,GAAG,8BAAgB;IACnB,GAAG,iBAAS;IACZ,GAAG,mBAAU;IACb,GAAG,sBAAY;IACf,GAAG,sBAAY;IACf,GAAG,yBAAa;IAChB,GAAG,wBAAa;IAChB,GAAG,yBAAa;IAChB,GAAG,gBAAS;CACb,CAAC;AAEW,QAAA,WAAW,GAAiC,IAAI,GAAG,CAC9D,gBAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAC/B,CAAC;AAEF,4CAA0B;AAC1B,+CAA6B;AAC7B,8CAA4B;AAC5B,8CAA4B;AAC5B,yCAAuB;AACvB,4CAA0B;AAC1B,4CAA0B;AAC1B,2CAAyB;AACzB,4CAA0B;AAC1B,0CAAwB;AACxB,6CAA2B;AAC3B,gDAA8B;AAC9B,mCAA0C;AAAjC,wGAAA,cAAc,OAAA"}

package/bin/tools/moments.d.ts

@@ -0,0 +1,9 @@
+import { Doc } from './shared';
+/** A moment as the list shows it. */
+export declare function momentRow(m: Doc): Doc;
+export declare const listMoments: import("../tool").AnyTool;
+export declare const getMoment: import("../tool").AnyTool;
+export declare const createMoment: import("../tool").AnyTool;
+export declare const updateMoment: import("../tool").AnyTool;
+export declare const deleteMoment: import("../tool").AnyTool;
+export declare const momentTools: import("../tool").AnyTool[];

package/bin/tools/moments.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.momentTools = exports.deleteMoment = exports.updateMoment = exports.createMoment = exports.getMoment = exports.listMoments = void 0;
+exports.momentRow = momentRow;
+/**
+ * Moments (the API's ad units): named points in an agent's conversation
+ * where an offer may appear. Each belongs to one agent.
+ */
+const offer_rules_1 = require("@advertising-chat/offer-rules");
+const zod_1 = require("zod");
+const tool_1 = require("../tool");
+const shared_1 = require("./shared");
+const code = zod_1.z
+    .string()
+    .min(1)
+    .max(100)
+    .describe('What the agent sends on each request to name this moment, e.g. `billing-answered`. Unique within the agent.');
+const description = zod_1.z
+    .string()
+    .max(1000)
+    .describe('What the moment means in the conversation, in a sentence. Rules and the Assistant rely on it.');
+const source = zod_1.z
+    .enum(offer_rules_1.MOMENT_SOURCES)
+    .describe('Who reports the moment: `agent` (the default) or `context_layer`.');
+/** The words for a moment's fields, for approval sentences. */
+const MOMENT_WORDS = {
+    name: 'name',
+    code: 'code',
+    description: 'description',
+    source: 'source',
+};
+/** A moment as the list shows it. */
+function momentRow(m) {
+    return {
+        id: (0, shared_1.str)(m._id) ?? (0, shared_1.str)(m.id),
+        code: (0, shared_1.str)(m.code),
+        name: m.name,
+        description: (0, shared_1.str)(m.description),
+        enabled: m.enabled,
+        application: (0, shared_1.refId)(m.application),
+    };
+}
+exports.listMoments = (0, tool_1.defineTool)({
+    name: 'list_moments',
+    title: 'List moments',
+    description: 'The org’s moments: the points in an agent’s conversation where an offer may appear (the API calls them ad units). Returns id, code (what the agent sends), name, description, enabled, and the agent (application) each belongs to. Every moment belongs to one agent, and codes are unique within an agent. Pass `application` to list one agent’s moments. Maps to GET /system/offer-manager/adunit.',
+    kind: 'read',
+    roleFloor: 'viewer',
+    input: {
+        application: shared_1.application.optional(),
+        ...shared_1.listShape,
+    },
+    async run({ client }, args) {
+        const body = await client.get(`${shared_1.OM}/adunit`, (0, shared_1.defined)(args));
+        return (0, shared_1.rows)(body).map(momentRow);
+    },
+});
+exports.getMoment = (0, tool_1.defineTool)({
+    name: 'get_moment',
+    title: 'Get a moment',
+    description: 'One moment with every field. Maps to GET /system/offer-manager/adunit/{id}.',
+    kind: 'read',
+    roleFloor: 'viewer',
+    input: { id: (0, shared_1.id)('moment') },
+    async run({ client }, { id: momentId }) {
+        return client.get(`${shared_1.OM}/adunit/${(0, shared_1.enc)(momentId)}`);
+    },
+});
+exports.createMoment = (0, tool_1.defineTool)({
+    name: 'create_moment',
+    title: 'Create a moment',
+    description: 'Create a moment for one agent. The agent must then send its `code` on requests at that point in the conversation; until it does, no offer appears there. A moment serves nothing until a rule or the agent’s network switch includes it. `application` is fixed once created. Maps to POST /system/offer-manager/adunit.',
+    kind: 'write',
+    roleFloor: 'editor',
+    input: {
+        application: shared_1.application,
+        name: zod_1.z.string().min(1).max(200).describe('Display name.'),
+        code,
+        description: description.optional(),
+        source: source.optional(),
+        enabled: zod_1.z.boolean().optional().describe('Default true.'),
+    },
+    approval: args => `Add the moment ${(0, shared_1.quoted)(args.name, '')} to this agent. The agent reports it by sending the code “${args.code}”; offers or ads from the network appear there only once an offer’s audience or the agent’s Ads from the network includes it.`,
+    async run({ client }, args) {
+        return client.post(`${shared_1.OM}/adunit`, (0, shared_1.defined)(args));
+    },
+});
+exports.updateMoment = (0, tool_1.defineTool)({
+    name: 'update_moment',
+    title: 'Update a moment',
+    description: 'Change a moment. Only the fields given change. Changing `code` breaks the agent’s requests until the agent sends the new code; disabling a moment stops every offer at it at once. Maps to PATCH /system/offer-manager/adunit/{id}.',
+    kind: 'write',
+    roleFloor: 'editor',
+    reader: 'get_moment',
+    input: {
+        id: (0, shared_1.id)('moment'),
+        application: shared_1.applicationOfUpdate,
+        name: zod_1.z.string().min(1).max(200).optional(),
+        code: code.optional(),
+        description: description.optional(),
+        source: source.optional(),
+        enabled: zod_1.z.boolean().optional(),
+    },
+    approval: (args, before) => {
+        const name = (0, shared_1.named)('moment', before?.name ?? args.name);
+        const rest = { ...args, enabled: undefined };
+        const what = (0, shared_1.changedWords)(rest, MOMENT_WORDS);
+        const parts = [];
+        if (args.enabled === false)
+            parts.push(`Turn off ${name}: no offer or network ad appears there until it is turned back on.`);
+        if (args.enabled === true)
+            parts.push(`Turn on ${name}.`);
+        if (what.length)
+            parts.push(`Change the ${(0, shared_1.listWords)(what)} of ${name}.${args.code !== undefined && args.code !== before?.code
+                ? ' The agent must send the new code, or no offer appears there.'
+                : ''}`);
+        return parts.join(' ') || `Change ${name}.`;
+    },
+    async run({ client }, args) {
+        return client.patch(`${shared_1.OM}/adunit/${(0, shared_1.enc)(args.id)}`, (0, shared_1.patchBody)(args, ['application']));
+    },
+});
+exports.deleteMoment = (0, tool_1.defineTool)({
+    name: 'delete_moment',
+    title: 'Delete a moment',
+    description: 'Permanently delete a moment. Refused (409) while a rule still includes it; the error names those rules. Requests the agent still sends with its code then get no offer. Maps to DELETE /system/offer-manager/adunit/{id}.',
+    kind: 'destructive',
+    roleFloor: 'editor',
+    reader: 'get_moment',
+    input: { id: (0, shared_1.id)('moment') },
+    approval: (_args, before) => `Delete ${(0, shared_1.named)('moment', before?.name)} for good. Requests the agent still sends for it get no offer.`,
+    async run({ client }, { id: momentId }) {
+        return client.delete(`${shared_1.OM}/adunit/${(0, shared_1.enc)(momentId)}`);
+    },
+});
+exports.momentTools = [
+    exports.listMoments,
+    exports.getMoment,
+    exports.createMoment,
+    exports.updateMoment,
+    exports.deleteMoment,
+];
+//# sourceMappingURL=moments.js.map

package/bin/tools/moments.js.map

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