@agency-tbd/cli 0.5.0 → 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 +69 -3
- package/dist/agent.js +36 -0
- package/dist/catalog.js +3 -2
- package/dist/commands.js +3 -3
- package/dist/files.js +86 -57
- package/dist/help.js +11 -1
- package/dist/schema.js +19 -2
- package/package.json +1 -2
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
|
|
@@ -127,7 +129,25 @@ Cursor pagination uses `--max-pages N`, optionally `--cursor-field nextCursor --
|
|
|
127
129
|
|
|
128
130
|
`batch --input @operations.json` takes an array of `{ "resource": "clients", "path": ["list"], "input": { "limit": 1 } }` entries. Execution is sequential and non-atomic, stops at the first failure, and reports completed/remaining entries. `--dry-run` validates entries without executing their business handlers. Never rerun an entire partially completed batch blindly.
|
|
129
131
|
|
|
130
|
-
Use `files routes` before `files upload <route> <file...> --type MIME
|
|
132
|
+
Use `files routes` before `files upload <route> <file...> --type MIME` to see each route's accepted types and size limits. File uploads are not API operations: `operations file-uploads` only lists and deletes existing files. Downloads use `files download <key> --output new-file`.
|
|
133
|
+
|
|
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.
|
|
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
|
+
|
|
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.
|
|
147
|
+
|
|
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.
|
|
149
|
+
|
|
150
|
+
Provider OAuth and device approval require browser consent. Provider credentials and provider readiness remain separate constraints.
|
|
131
151
|
|
|
132
152
|
`http` is an advanced same-origin escape hatch. The route inventory contains internal-service routes, provider callbacks and webhooks as well as ordinary app endpoints. Listing does not imply bearer-token support or permission; follow the existing application flow and never invoke callbacks or webhooks as substitutes for it. Raw HTTP has no generic dry-run. See [HTTP transport](src/transport.ts) and [file transport](src/files.ts).
|
|
133
153
|
|
|
@@ -173,7 +193,24 @@ For repository development, install dependencies with `pnpm install --frozen-loc
|
|
|
173
193
|
|
|
174
194
|
Before publishing, run `pnpm --filter @agency-tbd/cli release:check` on a supported Node.js release. It runs type checks, CLI tests, catalog validation and an isolated npm installation of the actual packed archive. Package contents are limited to compiled JavaScript, the README and package metadata; repository source, tests, source maps and local configuration are excluded. `pnpm pack` replaces workspace catalog references with installable dependency versions.
|
|
175
195
|
|
|
176
|
-
|
|
196
|
+
[`published-http-routes.json`](published-http-routes.json) names the oldest supported CLI release and lists every route and named resource that supported releases need. Tests fail if the CLI calls something undeclared or the server removes something listed. Add new calls when you write them. Remove an entry only after a CLI without it is on npm, and only with the version raised to that release. Tests cannot see npm, so reviewers must check that step. Merging does not publish: until the release is on npm, `@latest` keeps the old behavior.
|
|
197
|
+
|
|
198
|
+
Hosted Actions cannot currently start jobs, so publish from this Mac with the [release script](../../scripts/cli-release.mjs). Log in with `npm login` as a package maintainer, check out the latest `main`, and first confirm that required backend migrations and deployment are done:
|
|
199
|
+
|
|
200
|
+
```sh
|
|
201
|
+
corepack pnpm cli:publish --sha <main-commit> --version <version> --dry-run
|
|
202
|
+
corepack pnpm cli:publish --sha <main-commit> --version <version> --backend-ready
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
The command requires that the commit is the latest `main`, is the merge of a pull request whose identical source passed `local-gate/ci:check` with the service suites, and has that unpublished version. It builds and qualifies a fresh copy of the commit with a frozen install, publishes once using npm's own authentication prompts, then checks the registry archive, the `latest` tag and an anonymous installation. `--dry-run` needs no login and writes nothing to the registry: it stops at `npm publish --dry-run`, then runs the anonymous-install check against the current `latest`. Unknown flags are refused.
|
|
206
|
+
|
|
207
|
+
If you interrupt a run, its temporary copy stays registered; `git worktree prune` clears it once the folder is gone.
|
|
208
|
+
|
|
209
|
+
`npm publish` is never retried. After an uncertain result the archive is kept, its path and integrity are printed, and `node scripts/cli-release.mjs verify-published <version> <integrity>` rechecks the registry.
|
|
210
|
+
|
|
211
|
+
Publishing this way gives up safeguards the workflow has: npm's short-lived trusted identity, the environment's `main`-only rule, separate jobs for publishing and verifying, and pinned Node.js and npm versions. The gate status is reported by a local machine, so it is only as strong as the accounts that can write commit statuses.
|
|
212
|
+
|
|
213
|
+
If Actions runs again, the manually dispatched [Publish CLI workflow](../../.github/workflows/publish-cli.yml) applies the same source check. Select `main` and supply the full reviewed commit SHA, the CLI version and confirmation that required backend migrations/deployment have been verified. The workflow repeats package qualification, and publishes the same archived bytes using npm's short-lived GitHub identity. A separate job with no publishing permission verifies registry integrity, the `latest` tag and an anonymous installation. Readback waits up to ten minutes for the version, latest tag and npm installation metadata to agree, then installs with a fresh anonymous cache. Only readback requests may be retried; the publish command is never retried automatically. It has no npm token and requires no per-release security-key challenge. A failed or timed-out publication must be reconciled against the registry before another dispatch; an existing version is rejected rather than republished.
|
|
177
214
|
|
|
178
215
|
One-time setup by a package maintainer:
|
|
179
216
|
|
|
@@ -182,7 +219,7 @@ One-time setup by a package maintainer:
|
|
|
182
219
|
3. In the [npm package settings](https://www.npmjs.com/package/@agency-tbd/cli/access), add a GitHub Actions trusted publisher for owner `eternalwaitt`, repository `agency-tbd`, workflow filename `publish-cli.yml`, environment `npm-publish`, and direct `npm publish` permission. This configuration requires npm's security-key authorization once. Equivalently, use `npm trust github @agency-tbd/cli --repo eternalwaitt/agency-tbd --file publish-cli.yml --environment npm-publish --allow-publish` with a supported npm CLI and complete that one setup authorization. Preserve any existing publisher configurations.
|
|
183
220
|
4. Run the workflow for the reviewed main SHA and inspect its registry/install verification. Trust setup alone does not prove a publication works. This repository is private, so npm provenance is disabled; the workflow still authenticates through OIDC and verifies the archive checksum.
|
|
184
221
|
|
|
185
|
-
|
|
222
|
+
npm may require a separate 2FA challenge for each publish even after login. Do not use repeated login/publish attempts as the normal release process. Direct-publish bypass tokens are being retired in January 2027; they are not the durable automation path. See [npm trusted publishing](https://docs.npmjs.com/trusted-publishers/) and [token policy](https://docs.npmjs.com/about-access-tokens/).
|
|
186
223
|
|
|
187
224
|
CLI-only releases need no application deployment. New server-backed features such as support require the matching backend migration, configuration and deployment before publishing the CLI that advertises them. For each subsequent release, increment `apps/cli/package.json`'s version before review and publication; the CLI version output and API compatibility header read that same version. Do not reuse a published version. Do not claim installation from the registry works until the release is visible and verified there.
|
|
188
225
|
|
|
@@ -289,3 +326,32 @@ then UUID descending. Activity remains the default order. Follow `nextCursor` wi
|
|
|
289
326
|
the same filters/order; restart when those change. Pagination is over a changing
|
|
290
327
|
list, so restart for a current inventory if reports change while paging. Deploy the
|
|
291
328
|
backend/migration before publishing the CLI; publishing is a separate action.
|
|
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
|
+
|
|
339
|
+
## Externally signed participant contracts
|
|
340
|
+
|
|
341
|
+
For a final PDF already signed outside Influmode and retained in Google Drive, discover
|
|
342
|
+
`help contracts registerExternalDocument`. Use a new, untouched influencer contract draft
|
|
343
|
+
(with no versions, signers or signature invitations), the exact Drive file-view HTTPS URL,
|
|
344
|
+
filename and SHA-256 supplied by the operator, and `signedExternally:true` only after the
|
|
345
|
+
operator has confirmed external signing. This registers a reference; it does not upload or
|
|
346
|
+
fetch the PDF, verify its bytes/signatures, change Drive sharing, or send an invitation.
|
|
347
|
+
The contract becomes active with `signingSource:external`; its hash is operator-attested.
|
|
348
|
+
No signer records or signing timestamps are invented. The reference is immutable through
|
|
349
|
+
this operation and `addVersion`; repeating the identical registration is a no-op, and a
|
|
350
|
+
changed payload is rejected.
|
|
351
|
+
|
|
352
|
+
Read the contract back, then use `campaigns linkInfluencerContract` with the exact participant
|
|
353
|
+
and matching influencer contract. Read that participant back before proceeding to another.
|
|
354
|
+
The existing participant-link checks prevent cross-influencer and cross-tenant association;
|
|
355
|
+
replacing an existing link requires its previously read contract ID. These commands remain
|
|
356
|
+
subject to normal business-write approval. `contracts addVersion` continues to accept only
|
|
357
|
+
tenant-owned uploaded files and must not be used for a Drive reference.
|
package/dist/agent.js
CHANGED
|
@@ -23,6 +23,34 @@ export const agentGuide = {
|
|
|
23
23
|
retry: "Never automatically retry a mutation after an ambiguous failure; inspect saved state first.",
|
|
24
24
|
coverage: "API access does not reproduce UI preparation or prove every workflow is executable.",
|
|
25
25
|
},
|
|
26
|
+
files: {
|
|
27
|
+
upload: "File uploads are not API operations: run influmode files routes, then influmode files upload <route> <file> --type MIME. operations file-uploads only lists and deletes existing files.",
|
|
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
|
+
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
|
+
},
|
|
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
|
+
},
|
|
26
54
|
support: {
|
|
27
55
|
purpose: "Report bugs, compatibility problems, missing platform features or questions to the InfluMode team without GitHub access.",
|
|
28
56
|
help: "influmode support --help",
|
|
@@ -88,6 +116,14 @@ export const agentGuide = {
|
|
|
88
116
|
},
|
|
89
117
|
campaignDetail: { id: "<UUID>", acceptDeferredCollections: true },
|
|
90
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
|
+
},
|
|
91
127
|
output: {
|
|
92
128
|
stdout: "JSON {ok,data}",
|
|
93
129
|
stderr: "Progress or JSON {ok:false,error}",
|
package/dist/catalog.js
CHANGED
|
@@ -71,6 +71,7 @@ export const httpRoutes = [
|
|
|
71
71
|
"/api/pre-sign/[signerId]/sign",
|
|
72
72
|
"/api/probe/veloz-revalidation",
|
|
73
73
|
"/api/public/documents/[address]",
|
|
74
|
+
"/api/receipts/[token]",
|
|
74
75
|
"/api/scraper/events",
|
|
75
76
|
"/api/slo",
|
|
76
77
|
"/api/social-auth/[provider]/callback",
|
|
@@ -83,8 +84,8 @@ export const httpRoutes = [
|
|
|
83
84
|
"/api/social-auth/instagram/deletion-status/[code]",
|
|
84
85
|
"/api/status",
|
|
85
86
|
"/api/status/source",
|
|
86
|
-
"/api/
|
|
87
|
-
"/api/
|
|
87
|
+
"/api/uploads",
|
|
88
|
+
"/api/uploads/[slug]",
|
|
88
89
|
"/api/v1/analytics/influencer-report/export",
|
|
89
90
|
"/api/v1/analytics/network-cash-lane-details/export",
|
|
90
91
|
"/api/v1/contract-generation/download",
|
package/dist/commands.js
CHANGED
|
@@ -3,7 +3,7 @@ import { positive } from "./args.js";
|
|
|
3
3
|
import { logout, status } from "./auth.js";
|
|
4
4
|
import { CliError } from "./errors.js";
|
|
5
5
|
import { batch, call } from "./execute.js";
|
|
6
|
-
import { download, upload } from "./files.js";
|
|
6
|
+
import { download, routes, upload } from "./files.js";
|
|
7
7
|
import { readJson } from "./input.js";
|
|
8
8
|
import { saveOutput } from "./output.js";
|
|
9
9
|
import { describe } from "./schema.js";
|
|
@@ -79,9 +79,9 @@ async function callOptions(values) {
|
|
|
79
79
|
async function fileCommand(connection, { values, positionals }) {
|
|
80
80
|
const [, subcommand, ...rest] = positionals;
|
|
81
81
|
if (subcommand === "routes")
|
|
82
|
-
return (
|
|
82
|
+
return routes(connection);
|
|
83
83
|
if (subcommand === "upload" && rest[0])
|
|
84
|
-
return upload(connection, rest[0], rest.slice(1), values.type ?? "application/octet-stream",
|
|
84
|
+
return upload(connection, rest[0], rest.slice(1), values.type ?? "application/octet-stream", values["dry-run"] ?? false);
|
|
85
85
|
if (subcommand === "download" && rest[0] && values.output)
|
|
86
86
|
return download(connection, rest[0], values.output);
|
|
87
87
|
throw new CliError("USAGE", "Use files routes, upload <route> <file...> --type MIME, or download <key> --output file", 2);
|
package/dist/files.js
CHANGED
|
@@ -1,82 +1,111 @@
|
|
|
1
|
+
import { randomUUID } from "node:crypto";
|
|
1
2
|
import { readFile } from "node:fs/promises";
|
|
2
3
|
import { basename } from "node:path";
|
|
3
4
|
import { CliError } from "./errors.js";
|
|
4
5
|
import { saveOutput } from "./output.js";
|
|
5
|
-
import { http } from "./transport.js";
|
|
6
|
-
|
|
7
|
-
|
|
6
|
+
import { apiPath, http } from "./transport.js";
|
|
7
|
+
import { cliVersion } from "./version.js";
|
|
8
|
+
/** Failures whose own code tells the caller what to do next, unlike a generic upload failure. */
|
|
9
|
+
const SELF_EXPLAINING_CODES = new Set(["INCOMPATIBLE_SERVER", "UNKNOWN_UPLOAD_ROUTE"]);
|
|
10
|
+
function isRecord(value) {
|
|
11
|
+
return typeof value === "object" && value !== null;
|
|
12
|
+
}
|
|
13
|
+
/** A route that should exist returned 404: the installed CLI and this server have diverged. */
|
|
14
|
+
function incompatibleServer(pathname) {
|
|
15
|
+
return new CliError("INCOMPATIBLE_SERVER", `CLI ${cliVersion} and this server do not match: ${pathname} does not exist. Update with npm install --global @agency-tbd/cli@latest; if it is already the latest, report it with influmode support.`, 5, { cliVersion, path: pathname, status: 404 });
|
|
16
|
+
}
|
|
17
|
+
/** Lists the upload routes with their accepted types and size limits. */
|
|
18
|
+
export async function routes(connection) {
|
|
19
|
+
try {
|
|
20
|
+
return (await (await http(connection, "/api/uploads")).json());
|
|
21
|
+
}
|
|
22
|
+
catch (error) {
|
|
23
|
+
if (error instanceof CliError &&
|
|
24
|
+
error.code === "HTTP_ERROR" &&
|
|
25
|
+
isRecord(error.details) &&
|
|
26
|
+
error.details["status"] === 404)
|
|
27
|
+
throw incompatibleServer("/api/uploads");
|
|
28
|
+
throw error;
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
/** A system code or error type only: a transport message may repeat local or request details. */
|
|
32
|
+
function transportCause(error) {
|
|
33
|
+
const code = isRecord(error.cause) ? error.cause["code"] : undefined;
|
|
34
|
+
return typeof code === "string" ? code : error.name;
|
|
35
|
+
}
|
|
36
|
+
/** Keeps the reason a file failed alongside the files that were already stored. */
|
|
37
|
+
function batchFailure(error, completed, failedIndex) {
|
|
38
|
+
const failed = error instanceof CliError ? error : null;
|
|
39
|
+
return new CliError(failed && SELF_EXPLAINING_CODES.has(failed.code) ? failed.code : "UPLOAD_FAILED", `${failed?.message ?? "File upload failed"}; inspect completed files before retrying`, failed?.exitCode ?? 1, {
|
|
40
|
+
completed,
|
|
41
|
+
failedIndex,
|
|
42
|
+
...(failed?.details ? { failure: failed.details } : {}),
|
|
43
|
+
...(!failed && error instanceof Error ? { failure: { cause: transportCause(error) } } : {}),
|
|
44
|
+
});
|
|
45
|
+
}
|
|
46
|
+
/** Sends each file to the same tenant-authorized private upload route the UI uses. */
|
|
47
|
+
export async function upload(connection, slug, filenames, type, dryRun) {
|
|
8
48
|
if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(slug) || !filenames.length)
|
|
9
49
|
throw new CliError("USAGE", "Use files upload <route> <file...> --type <mime>", 2);
|
|
10
50
|
const files = await Promise.all(filenames.map(async (name) => new File([await readFile(name)], basename(name), { type })));
|
|
11
|
-
const
|
|
12
|
-
input: input ?? null,
|
|
13
|
-
files: files.map((file) => ({
|
|
14
|
-
name: file.name,
|
|
15
|
-
size: file.size,
|
|
16
|
-
type: file.type,
|
|
17
|
-
lastModified: file.lastModified,
|
|
18
|
-
})),
|
|
19
|
-
};
|
|
51
|
+
const described = files.map((file) => ({ name: file.name, size: file.size, type: file.type }));
|
|
20
52
|
if (dryRun)
|
|
21
|
-
return { executed: false, validated: false, route: slug, files:
|
|
22
|
-
const response = await http(connection, `/api/uploadthing?actionType=upload&slug=${encodeURIComponent(slug)}`, "POST", body, { "x-uploadthing-version": "7.7.4", "x-uploadthing-package": "influmode-cli" });
|
|
23
|
-
const data = await response.json();
|
|
24
|
-
if (!Array.isArray(data) || data.length !== files.length)
|
|
25
|
-
throw new CliError("UPLOAD_PROTOCOL_ERROR", "Invalid upload allocation", 1);
|
|
53
|
+
return { executed: false, validated: false, route: slug, files: described };
|
|
26
54
|
const results = [];
|
|
27
|
-
for (const [index,
|
|
28
|
-
const file = files[index];
|
|
29
|
-
if (!file)
|
|
30
|
-
throw new CliError("UPLOAD_PROTOCOL_ERROR", "Missing upload file", 1);
|
|
55
|
+
for (const [index, file] of files.entries()) {
|
|
31
56
|
try {
|
|
32
|
-
results.push(await
|
|
57
|
+
results.push(await uploadOne(connection, slug, file));
|
|
33
58
|
}
|
|
34
|
-
catch {
|
|
35
|
-
throw
|
|
59
|
+
catch (error) {
|
|
60
|
+
throw batchFailure(error, results, index);
|
|
36
61
|
}
|
|
37
62
|
}
|
|
38
63
|
return { files: results };
|
|
39
64
|
}
|
|
40
|
-
function
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
throw new CliError("UPLOAD_PROTOCOL_ERROR", "Untrusted upload target", 1);
|
|
54
|
-
return { url, key: raw.key };
|
|
55
|
-
}
|
|
56
|
-
async function uploadAllocated(connection, raw, file) {
|
|
57
|
-
const { url, key } = uploadTarget(raw);
|
|
58
|
-
const form = new FormData();
|
|
59
|
-
form.append("file", file);
|
|
60
|
-
// Bearer credentials are sent only to Influmode, never to storage.
|
|
61
|
-
const uploaded = await fetch(url, {
|
|
62
|
-
method: "PUT",
|
|
63
|
-
body: form,
|
|
64
|
-
headers: { Range: "bytes=0-", "x-uploadthing-version": "7.7.4" },
|
|
65
|
-
redirect: "error",
|
|
65
|
+
async function uploadOne(connection, slug, file) {
|
|
66
|
+
const response = await fetch(apiPath(connection.origin, `/api/uploads/${slug}`), {
|
|
67
|
+
method: "POST",
|
|
68
|
+
body: new Uint8Array(await file.arrayBuffer()),
|
|
69
|
+
headers: {
|
|
70
|
+
Authorization: `Bearer ${connection.token}`,
|
|
71
|
+
"content-type": file.type || "application/octet-stream",
|
|
72
|
+
// The upload route accepts only requests that name the app's own origin.
|
|
73
|
+
origin: connection.origin,
|
|
74
|
+
"x-correlation-id": connection.requestId ?? randomUUID(),
|
|
75
|
+
"x-upload-file-name": encodeURIComponent(file.name),
|
|
76
|
+
},
|
|
77
|
+
redirect: "manual",
|
|
66
78
|
signal: AbortSignal.timeout(connection.timeout),
|
|
67
79
|
});
|
|
68
|
-
if (!
|
|
69
|
-
throw
|
|
70
|
-
const result = await
|
|
71
|
-
if (!result || typeof result
|
|
72
|
-
throw new CliError("
|
|
80
|
+
if (!response.ok)
|
|
81
|
+
throw await uploadFailure(response, slug);
|
|
82
|
+
const result = await response.json();
|
|
83
|
+
if (!isRecord(result) || typeof result["key"] !== "string")
|
|
84
|
+
throw new CliError("UPLOAD_PROTOCOL_ERROR", "Invalid upload response", 1);
|
|
85
|
+
const reference = isRecord(result["serverData"]) ? result["serverData"]["fileUrl"] : undefined;
|
|
73
86
|
return {
|
|
74
|
-
key,
|
|
87
|
+
key: result["key"],
|
|
75
88
|
name: file.name,
|
|
76
89
|
size: file.size,
|
|
77
|
-
|
|
90
|
+
// The form receiptUrl and other file fields accept; a bare key is rejected there.
|
|
91
|
+
...(typeof reference === "string" ? { reference } : {}),
|
|
92
|
+
...("serverData" in result ? { serverData: result["serverData"] } : {}),
|
|
78
93
|
};
|
|
79
94
|
}
|
|
95
|
+
/** The server's stable failure code, when the response carries one. */
|
|
96
|
+
async function failureCode(response) {
|
|
97
|
+
const body = await response.json().catch(() => null);
|
|
98
|
+
const code = isRecord(body) ? body["code"] : null;
|
|
99
|
+
return typeof code === "string" && /^[A-Z_]{1,64}$/u.test(code) ? code : null;
|
|
100
|
+
}
|
|
101
|
+
async function uploadFailure(response, slug) {
|
|
102
|
+
const code = await failureCode(response);
|
|
103
|
+
if (code === "UNKNOWN_UPLOAD_ROUTE")
|
|
104
|
+
return new CliError(code, `Unknown upload route ${slug}; run influmode files routes`, 2);
|
|
105
|
+
if (response.status === 404)
|
|
106
|
+
return incompatibleServer(`/api/uploads/${slug}`);
|
|
107
|
+
return new CliError("UPLOAD_FAILED", `Upload failed with HTTP ${response.status}${code ? ` (${code})` : ""}`, response.status === 401 ? 3 : response.status === 403 ? 4 : 1, { status: response.status, ...(code ? { code } : {}) });
|
|
108
|
+
}
|
|
80
109
|
export async function download(connection, key, output) {
|
|
81
110
|
return saveOutput(output, () => http(connection, `/api/files/${encodeURIComponent(key)}`));
|
|
82
111
|
}
|
package/dist/help.js
CHANGED
|
@@ -34,7 +34,7 @@ Draft/preview are offline. Draft adds only CLI/Node/OS/architecture diagnostics
|
|
|
34
34
|
capabilities: "influmode capabilities [resource] [--search text]\nRead current account context and explicit execution limits. Optional resource adds live operation summaries. Effective operation permissions are not evaluated.",
|
|
35
35
|
schema: "influmode schema <resource> [operation.path]\nLive JSON input/output schemas. Requires login. Discovery does not evaluate permission or business state.",
|
|
36
36
|
batch: 'influmode batch --input @operations.json [--dry-run]\nInput: [{"resource":"clients","path":["list"],"input":{"limit":1}}]\nSequential, non-atomic; stops at the first failure. Inspect completed results before resuming. Dry-run validates inputs only.',
|
|
37
|
-
files: "influmode files routes\ninflumode files upload <route> <file...> --type MIME
|
|
37
|
+
files: "influmode files routes\ninflumode files upload <route> <file...> --type MIME\ninflumode files download <key> --output new-file\nInspect routes and their file limits first. Upload writes to Influmode private storage and returns a key and a reference. Use paymentDocument for receipts, then save that reference (not the key) in receiptUrl. Uploading never records or settles a payment. Downloads never overwrite files.",
|
|
38
38
|
http: "influmode http <GET|POST|PUT|PATCH|DELETE> /api/path [--input @input.json] [--output new-file]\nAdvanced escape hatch, restricted to the selected origin. Inspect the existing application flow first. No generic dry-run support. Do not use it to bypass permissions.",
|
|
39
39
|
call: "influmode call <resource> <operation.path> --input @input.json [--dry-run]\nEquivalent to influmode <resource> <operation.path>. Get the live schema first. Dry-run checks input only.",
|
|
40
40
|
guide: "influmode guide [--json]\nOffline agent workflow, execution limits, input conventions and recovery. skill is an alias.",
|
|
@@ -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
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@agency-tbd/cli",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.2",
|
|
4
4
|
"description": "Operate InfluMode from your terminal or AI assistant using your own account and permissions",
|
|
5
5
|
"homepage": "https://www.influmode.com",
|
|
6
6
|
"repository": {
|
|
@@ -41,7 +41,6 @@
|
|
|
41
41
|
"check-types": "tsc --noEmit",
|
|
42
42
|
"dev": "tsx src/main.ts",
|
|
43
43
|
"release:check": "pnpm check-types && pnpm test && node scripts/check-package.mjs",
|
|
44
|
-
"release:publish": "pnpm release:check && pnpm publish --access public",
|
|
45
44
|
"test": "pnpm build && vitest run --config vitest.config.ts"
|
|
46
45
|
}
|
|
47
46
|
}
|