@agency-tbd/cli 0.5.1 → 0.5.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +21 -0
- package/dist/agent.js +31 -0
- package/dist/catalog.js +1 -0
- package/dist/help.js +10 -0
- package/dist/schema.js +19 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -119,6 +119,8 @@ influmode clients byId --input @saved-record-id.json
|
|
|
119
119
|
|
|
120
120
|
Campaign detail calls require `{"id":"<UUID>","acceptDeferredCollections":true}`. Fetch related collection procedures when the full workspace is needed. An API operation may need preparation normally performed by the UI; schema discovery does not reproduce it.
|
|
121
121
|
|
|
122
|
+
Campaign rows from `campaigns list`, `campaigns byId`, `create` and `update` have two status fields. `status` is the saved workflow status. `effectiveStatus` is the status the app shows: a campaign saved as `ACTIVE` whose start date (São Paulo calendar day) is still ahead reads `SCHEDULED` ("Agendado"); every other status is the same in both fields. Use `effectiveStatus` to tell whether a campaign is running, and `status` only when you need the saved value, for example before changing it. The `campaigns list` `status` filter follows `effectiveStatus`: `"ACTIVE"` alone excludes future-dated `ACTIVE` campaigns, `"SCHEDULED"` includes them, and both together return all of them.
|
|
123
|
+
|
|
122
124
|
Use `--fields id,name` to project results and `--output new-file.json` for exports. For nested list data, a projection such as `--fields items,nextCursor` selects those fields; `--fields id` does not project into an `items` array. Exports reserve a new file before the operation and never overwrite existing files. See [execution](src/execute.ts) and [output](src/output.ts).
|
|
123
125
|
|
|
124
126
|
## Repetition, files and browser flows
|
|
@@ -131,6 +133,16 @@ Use `files routes` before `files upload <route> <file...> --type MIME` to see ea
|
|
|
131
133
|
|
|
132
134
|
To attach a receipt, upload it to the `paymentDocument` route (images and PDF, 4 MB each), which needs permission to edit campaigns. Each result has a `key` and a `reference`. Save the `reference`, such as `/api/files/<key>`, as `receiptUrl` with `financial recordPayment`, or with `financial updatePaymentMetadata` when the payment is already recorded; a bare key is rejected. Uploading never records or settles a payment.
|
|
133
135
|
|
|
136
|
+
Creator payout due date: `campaigns updateInfluencerPayoutDueDate` sets when a creator is paid. `terms.mode` is `NONE`, `FIXED_DATE` (`dueDate`), `TERM_DAYS` (`paymentTermDays` after `invoiceReceivedOn`), `FIRST_DELIVERY` or `LAST_DELIVERY` (`paymentTermDays` calendar days after the creator's first or last posted delivery in that campaign, using each delivery's publication date in São Paulo time). First delivery computes as soon as one dated publication exists; last delivery waits until every applicable delivery (not removed, not extra content) is posted and dated, and meanwhile `payoutDueDate` and `payoutDueReferenceOn` are `null`. A corrected publication date recomputes still-pending payments only. The operation needs permission to record payments, saves terms only and never records or settles a payment.
|
|
137
|
+
|
|
138
|
+
After recording a creator payout (for example with `campaigns updateInfluencerPaymentStatus`), `campaigns getInfluencerPaymentNotice` with `{"campaignInfluencerId":"<UUID>"}` returns the same "Avisar influenciador" text the payout editor copies: the organization's template, the latest amount and currency actually paid, the destination (a Pix key carries its type, such as `Pix CNPJ 00.000.000/0000-00`) and the receipt. Without a receipt the receipt lines are left out. `locale` is optional and defaults to the organization's language; pass the user's interface language to get exactly what their screen copies. It needs permission to record payments and never sends the text or changes the payment. `status: "UNAVAILABLE"` with `unavailableReason` explains a missing text. For a receipt uploaded to Influmode, the text carries a signed public link (`receiptAccess: "SIGNED"`, expiring at `receiptLinkExpiresAt`, 30 days by default): anyone holding the text can open that one receipt until it expires or is revoked. Each call issues a new link and records it in the audit log. `AGENCY_ONLY` means no link could be issued (for example, links are not configured on that server) and the creator cannot open the receipt; external links such as Drive are `EXTERNAL`. `financial revokeSettlementReceiptLinks` with `{"settlementId":"<UUID>"}` stops every link issued so far for that payment's receipt, and `settings updateReceiptLinkSettings` sets the period (1–90 days); both are changes that need the user's approval. Sending the text is a separate outbound action that needs the user's approval of recipient and text.
|
|
139
|
+
|
|
140
|
+
A campaign report's client access code ("Acesso do cliente") is hashed for verification and also stored encrypted so the agency can copy it again. These operations are in the `campaigns/portal` resource (not `campaigns`). `reportCodeStatus` with `{"campaignId":"<UUID>"}` returns `expiresAt`, `version` and `recoverable` (`null` when no code is valid) and never the code. `revealReportCode` returns the same active code and `reportUrl` and changes nothing; it needs the permission for creating codes and is audited. It is refused for codes created before copying existed (`recoverable` false): generate a new one. `createReportCode` with `days` 1, 7 or 30 returns a new code; to replace an active code, pass `expectedVersion` from `reportCodeStatus`. Replacing it or calling `campaigns/portal deleteReportCode` stops the old code and the sessions opened with it, so both need the user's approval.
|
|
141
|
+
|
|
142
|
+
Client contract amendments: `campaigns listContractAmendments` with `{"campaignId":"<UUID>"}` lists the named amendments of a campaign's client contract, and `campaigns attachContractAmendment` with `{"campaignId","name","fileUrl"}` adds one (for example "1º Termo Aditivo"; upload the file first and save its `reference` as `fileUrl`). Attaching never changes the main contract, campaign dates or receivables. `campaigns removeContractAmendment` with `{"campaignId","id"}` hides one amendment and keeps the stored file. Attaching and removing need permission to edit campaigns and the user's approval; after an uncertain attach, list the amendments before repeating.
|
|
143
|
+
|
|
144
|
+
Deliverables can carry an optional `referenceMonth` (`YYYY-MM`, `null` for no month): the month a deliverable fulfils in a monthly scope, independent of `dueDate` and `publishedAt`. A November deliverable published in December still counts in November and keeps its real `publishedAt`. Set it on `deliverables create`, `update` and `saveBatch` (`null` clears it); `deliverables list` accepts `referenceMonth` (`"none"` for deliverables without a month) together with `campaignId`; `campaigns getReport` accepts it for a monthly report and returns `referenceMonths` with planned, published and pending counts per month. `deliverables setReferenceMonth` with `{"campaignId":"<UUID>","ids":["<UUID>"],"referenceMonth":"2026-11"}` assigns a month to existing deliverables without changing links, dates, status or instalments. `deliverables copyReferenceMonthScope` with `{"campaignId":"<UUID>","fromMonth":"2026-11","toMonths":["2026-12"]}` repeats a month's agreed scope as new pending deliverables (never links, dates or statuses; extra content is skipped) in months that have none yet. Both are changes that need the user's approval.
|
|
145
|
+
|
|
134
146
|
After an uncertain link, read the payment back before repeating anything. An uncertain upload changes no payment, and repeating it stores a new file. `file-uploads list` needs user-management permission and does not show which payment uses a file.
|
|
135
147
|
|
|
136
148
|
Upload failures name the server's reason, such as `FILE_TOO_LARGE`, and list any files already completed. `INCOMPATIBLE_SERVER` means the installed CLI and the server have diverged: update the CLI rather than guessing another endpoint. CLI 0.5.0 cannot upload files or list upload routes, because it calls a route the server no longer has; use 0.5.1 or later.
|
|
@@ -315,6 +327,15 @@ the same filters/order; restart when those change. Pagination is over a changing
|
|
|
315
327
|
list, so restart for a current inventory if reports change while paging. Deploy the
|
|
316
328
|
backend/migration before publishing the CLI; publishing is a separate action.
|
|
317
329
|
|
|
330
|
+
## Contract creators
|
|
331
|
+
|
|
332
|
+
`contracts create` accepts the creator `id` that `influencers list` returns, or that row's
|
|
333
|
+
`tenantData.id`. Either must belong to a creator added to this organization; the contract stores
|
|
334
|
+
the organization's creator record, so reads return `tenantData.id` as `influencerId`. Creating
|
|
335
|
+
a contract does not add a creator, link a campaign participant or send an invitation.
|
|
336
|
+
To filter `contracts list` by creator, pass the creator `id` from `influencers list`, not a
|
|
337
|
+
contract's `influencerId`.
|
|
338
|
+
|
|
318
339
|
## Externally signed participant contracts
|
|
319
340
|
|
|
320
341
|
For a final PDF already signed outside Influmode and retained in Google Drive, discover
|
package/dist/agent.js
CHANGED
|
@@ -28,6 +28,29 @@ export const agentGuide = {
|
|
|
28
28
|
receipts: "Upload to the paymentDocument route, which needs permission to edit campaigns. Save the returned reference (not the key) as receiptUrl with financial recordPayment, or with financial updatePaymentMetadata when the payment is already recorded. Uploading never records or settles a payment.",
|
|
29
29
|
recovery: "After an uncertain link, read the payment back before repeating anything. An uncertain upload changes no payment; a repeat stores a new file. file-uploads list needs user-management permission and does not show which payment uses a file.",
|
|
30
30
|
},
|
|
31
|
+
payoutNotice: {
|
|
32
|
+
read: 'influmode campaigns getInfluencerPaymentNotice --input \'{"campaignInfluencerId":"UUID"}\' returns the same "Avisar influenciador" text the payout editor copies. Optional locale defaults to the organization language; pass the user\'s interface language to match what their screen copies.',
|
|
33
|
+
effect: "Needs payment-recording permission, sends nothing and does not change the payment. status UNAVAILABLE explains why there is no text yet.",
|
|
34
|
+
receipt: "For a receipt uploaded to Influmode the text carries a signed public link (receiptAccess SIGNED, expires at receiptLinkExpiresAt); anyone with the text can open that receipt until then. Each call issues a new link and an audit entry. AGENCY_ONLY means no link could be issued and the creator cannot open the receipt; say so instead of sending it as if it worked.",
|
|
35
|
+
revoke: 'financial revokeSettlementReceiptLinks --input \'{"settlementId":"UUID"}\' stops every link issued so far for that payment\'s receipt. settings updateReceiptLinkSettings sets the link period (1-90 days, default 30). Both are changes: obtain approval first.',
|
|
36
|
+
send: "Sending the text to the creator is a separate outbound action: show recipient and exact text and obtain approval first.",
|
|
37
|
+
},
|
|
38
|
+
payoutDueDate: {
|
|
39
|
+
set: "influmode campaigns updateInfluencerPayoutDueDate --input @due.json sets when a creator is paid in a campaign. Input: campaignInfluencerId, invoiceReceivedOn (YYYY-MM-DD or null), reminderDays (0-60 or null) and terms with mode NONE, FIXED_DATE (dueDate), TERM_DAYS (paymentTermDays after the NF received date), FIRST_DELIVERY or LAST_DELIVERY (paymentTermDays calendar days after the creator's first or last posted delivery in that campaign).",
|
|
40
|
+
delivery: "FIRST_DELIVERY computes as soon as one publication has a date. LAST_DELIVERY computes only when every applicable delivery (not removed, not extra content) is posted and dated. While it waits, payoutDueDate and payoutDueReferenceOn are null. A corrected publication date recomputes still-pending payments only; paid or partly paid ones keep their date.",
|
|
41
|
+
effect: "Needs payment-recording permission. It sets terms only: it never records a payment or changes its status.",
|
|
42
|
+
},
|
|
43
|
+
externalPayout: {
|
|
44
|
+
record: "influmode campaigns recordExternalInfluencerPayout --input @payout.json records a creator payout paid outside every agency account (for example a partner's crypto wallet). Required: campaignInfluencerId, amount (deducted from the balance owed, in the payout currency), paidAt, method, idempotencyKey (UUID) and reference or receiptUrl. Crypto also needs network; transferAmount and transferAsset go together.",
|
|
45
|
+
effect: "Lowers what the creator is owed and appears in the payout history as paid outside the agency account. It moves no agency account, needs no Pix key and never changes the creator's registered payment method. It is a payment: obtain approval first, and reuse the same idempotencyKey only to replay the identical request.",
|
|
46
|
+
compensation: 'A bank outflow that repaid whoever paid (a Despesa or salary withdrawal) is recorded once as that expense. Link it with compensationExpenseId when recording, or later with campaigns linkExternalPayoutCompensation --input \'{"settlementId":"UUID","compensationExpenseId":"UUID"}\' (null unlinks). campaigns externalPayoutOptions lists partners and unlinked expenses; pass campaignInfluencerId (or settlementId) and paidDate to get likely matches first (match CAMPAIGN, then PERIOD), and search to find the rest. Linking never posts a second debit, and the linked expense no longer counts as an agency cost in profit.',
|
|
47
|
+
undo: "Reversing the payout's PAID status reverses an external payment like any other, without touching an agency account.",
|
|
48
|
+
},
|
|
49
|
+
contractAmendments: {
|
|
50
|
+
list: 'influmode campaigns listContractAmendments --input \'{"campaignId":"UUID"}\' returns the named amendments (name, openable fileUrl, createdAt) of the client contract, oldest first. Removed amendments are not listed.',
|
|
51
|
+
attach: 'Upload the document with influmode files upload (see files routes), then influmode campaigns attachContractAmendment --input \'{"campaignId":"UUID","name":"1º Termo Aditivo","fileUrl":"/api/files/KEY"}\'. Needs permission to edit campaigns. It adds one document and never changes the main contract, campaign dates or receivables. It is a change: obtain approval first and never retry after an ambiguous failure; list the amendments instead.',
|
|
52
|
+
remove: 'influmode campaigns removeContractAmendment --input \'{"campaignId":"UUID","id":"UUID"}\' hides one amendment (soft delete; the stored file is kept). Same permission as attach.',
|
|
53
|
+
},
|
|
31
54
|
support: {
|
|
32
55
|
purpose: "Report bugs, compatibility problems, missing platform features or questions to the InfluMode team without GitHub access.",
|
|
33
56
|
help: "influmode support --help",
|
|
@@ -93,6 +116,14 @@ export const agentGuide = {
|
|
|
93
116
|
},
|
|
94
117
|
campaignDetail: { id: "<UUID>", acceptDeferredCollections: true },
|
|
95
118
|
},
|
|
119
|
+
campaigns: {
|
|
120
|
+
status: "status is the saved workflow status. effectiveStatus is what the app shows: ACTIVE with a future start date (São Paulo day) reads SCHEDULED (Agendado). Use effectiveStatus to say whether a campaign is running.",
|
|
121
|
+
statusFilter: 'campaigns list status filter follows effectiveStatus: "ACTIVE" alone excludes future-dated ACTIVE campaigns and "SCHEDULED" includes them.',
|
|
122
|
+
reportAccessCode: 'The campaign report\'s client access code ("Acesso do cliente") is kept hashed for verification plus an encrypted copy so the agency can copy it again. These operations live in the campaigns/portal resource, not campaigns: influmode campaigns/portal reportCodeStatus --input \'{"campaignId":"UUID"}\' returns expiresAt, version and recoverable (null: no valid code) and never the code. influmode campaigns/portal revealReportCode --input \'{"campaignId":"UUID"}\' returns the same active code and reportUrl without changing expiry, version or sessions; each reveal is audited, needs the same permission as creating a code, and is refused when no valid code exists or recoverable is false (created before copying existed: generate a new one). Never log, store or repeat a revealed code beyond what the user asked. createReportCode with days 1, 7 or 30 returns a new code and reportUrl; to replace an active code pass expectedVersion from reportCodeStatus, which stops the old code and its sessions. Replacing and deleteReportCode are changes: obtain approval first.',
|
|
123
|
+
},
|
|
124
|
+
deliverables: {
|
|
125
|
+
referenceMonth: 'A deliverable can carry referenceMonth ("YYYY-MM", null = no month): the month it fulfils in a monthly scope, independent of dueDate and publishedAt. A November deliverable published in December still counts in November and keeps its real publishedAt. Set it with deliverables create/update/saveBatch (update null clears it). deliverables list --input \'{"campaignId":"UUID","referenceMonth":"2026-11"}\' filters one month ("none" = deliverables without a month). campaigns getReport accepts the same referenceMonth for a monthly report and returns referenceMonths (planned/published/pending per month). deliverables setReferenceMonth --input \'{"campaignId":"UUID","ids":["UUID"],"referenceMonth":"2026-11"}\' assigns a month to existing deliverables without touching links, dates, status or instalments. deliverables copyReferenceMonthScope --input \'{"campaignId":"UUID","fromMonth":"2026-11","toMonths":["2026-12"]}\' repeats that month\'s agreed scope as new pending deliverables (definitions only, never links, dates or statuses; extra content is skipped) in months that have no deliverables yet. Both are changes: obtain approval first.',
|
|
126
|
+
},
|
|
96
127
|
output: {
|
|
97
128
|
stdout: "JSON {ok,data}",
|
|
98
129
|
stderr: "Progress or JSON {ok:false,error}",
|
package/dist/catalog.js
CHANGED
package/dist/help.js
CHANGED
|
@@ -66,6 +66,13 @@ Commercial records (leads, deals, campaigns):
|
|
|
66
66
|
influmode leads updates.updateState --input @next-step.json
|
|
67
67
|
Use the same updates operations for deals and campaigns. Run schema for exact inputs.
|
|
68
68
|
|
|
69
|
+
Creator payout notice ("Avisar influenciador"; sends nothing, never changes the payment):
|
|
70
|
+
influmode campaigns getInfluencerPaymentNotice --input '{"campaignInfluencerId":"UUID"}'
|
|
71
|
+
|
|
72
|
+
Creator payout due date (terms only; never records a payment). terms.mode NONE, FIXED_DATE, TERM_DAYS,
|
|
73
|
+
FIRST_DELIVERY or LAST_DELIVERY (calendar days after the first or last posted delivery):
|
|
74
|
+
influmode campaigns updateInfluencerPayoutDueDate --input '{"campaignInfluencerId":"UUID","invoiceReceivedOn":null,"reminderDays":3,"terms":{"mode":"LAST_DELIVERY","paymentTermDays":30}}'
|
|
75
|
+
|
|
69
76
|
Global: --url HTTPS_ORIGIN (or INFLUMODE_URL), --timeout milliseconds.
|
|
70
77
|
Root --help --json returns machine-readable usage and agent guidance.
|
|
71
78
|
Resource/operation --help inspects live metadata; it never executes that operation.
|
|
@@ -110,6 +117,9 @@ Use the first-party Influmode CLI for application operations.
|
|
|
110
117
|
14. Skip routine rereads and unchanged assessments. Update nextStep independently without deleting prior events.
|
|
111
118
|
Conversion history follows the original Lead/Deal relations under each parent's view permissions.
|
|
112
119
|
Preserve original free text; never invent dates or authors while summarizing it.
|
|
120
|
+
15. After recording a creator payout, campaigns getInfluencerPaymentNotice returns the "Avisar influenciador"
|
|
121
|
+
text. It sends nothing; sending it needs approval of recipient and exact text. An uploaded receipt becomes a
|
|
122
|
+
signed public link (receiptAccess SIGNED); AGENCY_ONLY means the creator cannot open that receipt.
|
|
113
123
|
|
|
114
124
|
Use --input @file or stdin to keep private payloads out of shell history.
|
|
115
125
|
Use --fields to reduce context; use --output for exports and binary downloads.
|
package/dist/schema.js
CHANGED
|
@@ -10,13 +10,23 @@ export function operationPath(resource, parts) {
|
|
|
10
10
|
throw new CliError("INVALID_OPERATION", "Provide a valid operation path; run schema <resource>", 2);
|
|
11
11
|
return parts;
|
|
12
12
|
}
|
|
13
|
+
function isNotFound(error) {
|
|
14
|
+
if (error instanceof CliError)
|
|
15
|
+
return (error.code === "NOT_FOUND" ||
|
|
16
|
+
error.details?.status === 404);
|
|
17
|
+
return !!error && typeof error === "object" && "code" in error && error.code === "NOT_FOUND";
|
|
18
|
+
}
|
|
13
19
|
export async function describe(connection, resource, path) {
|
|
14
20
|
if (connection.sponsorshipTenantId && resource !== "sponsorships")
|
|
15
21
|
throw new CliError("INVALID_TENANT_SCOPE", "--sponsor-tenant applies only to sponsorships", 2);
|
|
16
22
|
if (connection.sponsorshipTenantId && !/^[0-9a-f-]{36}$/i.test(connection.sponsorshipTenantId))
|
|
17
23
|
throw new CliError("INVALID_TENANT_SCOPE", "Invalid sponsorship tenant identifier", 2);
|
|
18
24
|
operationPath(resource, path?.length ? path : ["schema"]);
|
|
19
|
-
const result = await rpc(connection, resource, ["__cli", "schema"], path?.length ? { path } : undefined, "GET")
|
|
25
|
+
const result = await rpc(connection, resource, ["__cli", "schema"], path?.length ? { path } : undefined, "GET").catch((error) => {
|
|
26
|
+
if (path?.length && isNotFound(error))
|
|
27
|
+
throw missingOperation(resource, path);
|
|
28
|
+
throw error;
|
|
29
|
+
});
|
|
20
30
|
if (!result ||
|
|
21
31
|
typeof result !== "object" ||
|
|
22
32
|
!("protocolVersion" in result) ||
|
|
@@ -26,11 +36,18 @@ export async function describe(connection, resource, path) {
|
|
|
26
36
|
throw new CliError("INCOMPATIBLE_SERVER", "Server does not support CLI discovery v1; deploy the matching server changes", 5);
|
|
27
37
|
return result;
|
|
28
38
|
}
|
|
39
|
+
function missingOperation(resource, path) {
|
|
40
|
+
const related = resources.filter((item) => item.startsWith(`${resource}/`));
|
|
41
|
+
const hint = related.length
|
|
42
|
+
? ` Operations may live in a related resource: ${related.join(", ")}. Try operations <resource> --search ${path[0] ?? ""}.`
|
|
43
|
+
: "";
|
|
44
|
+
return new CliError("UNKNOWN_OPERATION", `Operation ${path.join(".")} not found in ${resource}.${hint}`, 2);
|
|
45
|
+
}
|
|
29
46
|
export async function resolveOperation(connection, resource, path) {
|
|
30
47
|
const result = await describe(connection, resource, operationPath(resource, path));
|
|
31
48
|
const operation = result.operations.find((item) => item.path.join(".") === path.join("."));
|
|
32
49
|
if (!operation)
|
|
33
|
-
throw
|
|
50
|
+
throw missingOperation(resource, path);
|
|
34
51
|
return operation;
|
|
35
52
|
}
|
|
36
53
|
//# sourceMappingURL=schema.js.map
|
package/package.json
CHANGED