Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
68 changes: 34 additions & 34 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ polymorfa version
## Requirements

- Node.js 22 or newer
- A Polymorfa organization API key or exact-project token for developer requests
- A Polymorfa team API key or exact-project token for developer requests
- A server API key or short-lived client token for Messaging requests

## Development installation
Expand Down Expand Up @@ -140,7 +140,7 @@ The registry comes from the real command files. Commands needing the installed C
## Authentication profiles

Until the backend exposes a revocable CLI device-authorization flow, login
accepts an organization API key or exact-project token through standard input:
accepts a team API key or exact-project token through standard input:

```shell
printf '%s' "$POLYMORFA_API_KEY" | \
Expand All @@ -154,7 +154,7 @@ printf '%s' "$POLYMORFA_PROJECT_TOKEN" | \
polymorfa auth login --with-project-token --project project_123 --profile project-work
```

Profile metadata records its explicit project or organization owner. Credentials
Profile metadata records its explicit project or team owner. Credentials
are stored separately in macOS Keychain, Windows Credential Manager, or Linux
Secret Service. A keyring failure stops the command; the CLI never silently
falls back to plaintext. `auth status` reports local secure-store availability
Expand Down Expand Up @@ -194,7 +194,7 @@ polymorfa project current # show the project and where it comes from

Commands resolve the project in this order: `--project`, the nearest
`polymorfa.json` in the current directory or a parent, then the
profile's stored project. Organization-owned commands ignore linked and profile
profile's stored project. Team-owned commands ignore linked and profile
projects. `--verbose` prints the link file in use.

`project use` and `link` accept a UUID or a unique slug and store the canonical
Expand Down Expand Up @@ -257,7 +257,7 @@ your shell to its startup file if you want completion in later sessions.

## Inspect sessions

Use an organization API key with `sessions:read` to inspect stored session
Use a team API key with `sessions:read` to inspect stored session
metadata:

```shell
Expand All @@ -272,12 +272,12 @@ Use a session ID from the list for `view` or `status`; these commands do not
accept `--project`. `status` reads the stored status and optional reason from
the session record. It does not probe the device or wait for a connection.
Key metadata listing and revocation are available through `key list` and
`key revoke`; the CLI does not mint or rotate organization keys.
`key revoke`; the CLI does not mint or rotate team keys.

## QuickLinks

A QuickLink is a persistent hosted link that connects one WhatsApp number to a
new session in a project. Create one from a JSON request with an organization
new session in a project. Create one from a JSON request with a team
API key that has `quicklink:manage`:

```shell
Expand All @@ -290,7 +290,7 @@ The request accepts `customerId`, `externalId`, and `configuration`. See
[Guided session creation and configuration](#guided-session-creation-and-configuration)
for the configuration fields.

Inspect or cancel a link with an organization API key or an exact-project
Inspect or cancel a link with a team API key or an exact-project
token that has `quicklink:manage`:

```shell
Expand All @@ -314,7 +314,7 @@ or history operation, so the CLI does not synthesize them.

## Customers

Manage Customers through the Platform API with an organization server key and
Manage Customers through the Platform API with a team server key and
an explicit project ID:

```shell
Expand Down Expand Up @@ -496,7 +496,7 @@ header.

### Flow drafts and provider lifecycle

Flow commands require a project scope and an organization API key or project
Flow commands require a project scope and a team API key or project
token. Reads use `sessions:read`; mutations use `sessions:manage`.

```shell
Expand Down Expand Up @@ -579,7 +579,7 @@ linked to another project; the API checks that the credential can access it.

### Official API observations and templates

The `cloud` commands require an organization API key or a project token with the
The `cloud` commands require a team API key or a project token with the
listed scope. Client tokens cannot use these commands. Server-side feature
access still applies: an installed command does not enroll a Number or enable a
beta feature.
Expand Down Expand Up @@ -1246,7 +1246,7 @@ sox greeting.wav -t raw -r 16000 -e signed -b 16 -c 1 - | \

Polymorfa checks every call against the team's call policy before the
destination rings. `calls policy` and `calls opt-outs` read and change that
policy and require an organization API key (`POLYMORFA_API_KEY` or a profile).
policy and require a team API key (`POLYMORFA_API_KEY` or a profile).
A project token used as the API key reaches the API, which refuses it with
`403` (exit code 3). A client token is not a Platform credential, so the CLI
refuses the command before sending a request (exit code 2).
Expand Down Expand Up @@ -1325,9 +1325,9 @@ polymorfa calls check +14155550123 --session support
### Call statistics and export

`calls stats` summarizes calls and `calls export` writes call detail records.
Both accept an organization API key or an exact-project token with the
Both accept a team API key or an exact-project token with the
`sessions:read` scope. Pass `--project` to read one project. Without it, an
organization API key reads every project in the organization. A project token
team API key reads every project in the team. A project token
reads only its own project and requires `--project`.

```shell
Expand Down Expand Up @@ -1416,7 +1416,7 @@ or times out, the command keeps the password on screen and exits successfully.
Voice Automation is a beta (`calls.voice-automation`) for enrolled teams only.
For other teams, every change except delete fails with `voice_not_enabled`.
Reads, previews and deletes keep working after a team leaves the beta. The
commands require an organization server API key with `voice:read` (lists,
commands require a team server API key with `voice:read` (lists,
views, previews) or `voice:manage` (changes).

### Audio library
Expand Down Expand Up @@ -1693,7 +1693,7 @@ request metadata.

## Platform access and security

Organization server API keys can inspect the credential, membership, audit,
Team server API keys can inspect the credential, membership, audit,
ban, incident, saved QuickLink settings, and project-token metadata made
available by the Platform API:

Expand Down Expand Up @@ -1746,7 +1746,7 @@ bypass.
returns `null` in JSON when no settings row has been saved. Update
accepts one bounded JSON object from `--input`; the target project is selected
separately with `--project` and cannot be hidden in that input. Omitting the
project targets organization defaults. Widget logo fields are existing storage
project targets team defaults. Widget logo fields are existing storage
identifiers, not file, URL, base64, upload, or download operations. Widget
access requires the `quicklink:manage` scope.

Expand Down Expand Up @@ -1776,7 +1776,7 @@ enqueue another request, while repeated deletion counts only rows still present.

## Messaging campaigns

Campaign commands use organization Messaging API keys and require an explicit
Campaign commands use team Messaging API keys and require an explicit
project slug because the source routes are slug-scoped:

```shell
Expand Down Expand Up @@ -2019,7 +2019,7 @@ or stop a campaign's operation, use the `operation` commands in

## Campaign audiences

Audience commands are organization-scoped and use the Platform API:
Audience commands are team-scoped and use the Platform API:

```shell
polymorfa audience create --name "August launch" \
Expand Down Expand Up @@ -2051,7 +2051,7 @@ recipient listing.

## Campaign opt-outs

Opt-out suppression is organization-wide. Keyword capture has its own settings:
Opt-out suppression is team-wide. Keyword capture has its own settings:

```shell
polymorfa optout settings view
Expand All @@ -2074,8 +2074,8 @@ recipient with `lastError` `opted_out`.
## Developer events and webhooks

Developer resources always have an explicit owner. Project-owned commands need
`--owner project --project <id>`. Organization-owned commands use
`--owner organization` and reject a project override. A stored profile can
`--owner project --project <id>`. Team-owned commands use
`--owner team` and reject a project override. A stored profile can
provide the owner, but the CLI never guesses it from a credential or retries a
request against a different owner.

Expand Down Expand Up @@ -2152,18 +2152,18 @@ operation ID in the JSON `operation.id` field. Follow it with

Campaign sends, production enrollments, and other durable work are tracked as
operations. The commands need `operations:read`; `operation cancel` needs
`operations:cancel`. With `--owner organization`, commands read team-owned
`operations:cancel`. With `--owner team`, commands read team-owned
operations and every project's operations. With `--owner project`, they read
one project.

```shell
polymorfa operation list --owner organization --status running
polymorfa operation list --owner organization \
polymorfa operation list --owner team --status running
polymorfa operation list --owner team \
--resource-type campaign --resource-id campaign_123
polymorfa operation view operation_123 --owner organization
polymorfa operation wait operation_123 --owner organization --timeout 600
polymorfa operation watch operation_123 --owner organization
polymorfa operation cancel operation_123 --owner organization --yes
polymorfa operation view operation_123 --owner team
polymorfa operation wait operation_123 --owner team --timeout 600
polymorfa operation watch operation_123 --owner team
polymorfa operation cancel operation_123 --owner team --yes
```

`operation wait` long-polls the API (up to 30 seconds per request) until the
Expand Down Expand Up @@ -2337,7 +2337,7 @@ status, and safe counters, never primary credentials, listener credentials,
forwarding secrets, or unrestricted payloads.

`polymorfa_session_list` is a read-only discovery tool for one explicit project
UUID. It uses the selected CLI organization API key with `sessions:read` and
UUID. It uses the selected CLI team API key with `sessions:read` and
returns session ID, name, stored status, and test-mode flag. It omits phone
numbers, credentials, and message data. The tool does not probe the live device.
Project tokens and Messaging client tokens cannot use this tool. A failed read
Expand Down Expand Up @@ -2575,7 +2575,7 @@ the CLI never creates or confirms a replacement purchase automatically.

### Number tier changes

Tier changes use an organization API key. Quote first, review the credit charge
Tier changes use a team API key. Quote first, review the credit charge
and effective time, then confirm that exact quote:

```shell
Expand Down Expand Up @@ -2664,7 +2664,7 @@ polymorfa hybrid-link resume --session NUMBER --expected-revision REVISION
For project and session routing scopes, `--project`, the nearest linked project,
and the selected profile determine the project in that order. A project-token
profile fails when its project differs from the linked directory. Team routing
scope uses an organization API key and ignores directory project links. `quicklink
scope uses a team API key and ignores directory project links. `quicklink
availability` shows existing connection status and any QuickLink that can be
resumed.

Expand All @@ -2685,7 +2685,7 @@ transports within the restrictions inherited from the team and project.

### Functions

Functions are project-owned. Select `--project` or use the linked project/profile context. The commands accept an organization API key or a project token; browser client tokens are refused. Access also depends on the team's enabled Functions release and the configured execution region.
Functions are project-owned. Select `--project` or use the linked project/profile context. The commands accept a team API key or a project token; browser client tokens are refused. Access also depends on the team's enabled Functions release and the configured execution region.

```bash
polymorfa function list --project PROJECT_UUID
Expand Down Expand Up @@ -2770,7 +2770,7 @@ does not retrieve media or webhook deliveries.

### Spending limits and funding priority

With an organization key carrying `billing:read`, inspect current controls:
With a team key carrying `billing:read`, inspect current controls:

```bash
polymorfa billing limits list --project <project-uuid> --json
Expand Down
4 changes: 2 additions & 2 deletions contracts/abprops-capabilities.json
Original file line number Diff line number Diff line change
Expand Up @@ -430,7 +430,7 @@
"whatsapp_group_suspended",
"whatsapp_group_has_no_participants",
"bansafe_suspended",
"bansafe_org_suspended",
"bansafe_team_suspended",
"bansafe_cold_blocked",
"bansafe_cold_held",
"bansafe_throttled",
Expand Down Expand Up @@ -458,7 +458,7 @@
"request_log_url": {
"type": "string",
"format": "uri",
"description": "Console page that shows this request. Returned only to organization and project credentials whose request was logged."
"description": "Console page that shows this request. Returned only to team and project credentials whose request was logged."
}
},
"required": ["type", "code", "message", "param", "request_id"]
Expand Down
8 changes: 4 additions & 4 deletions contracts/business-account-modes.json
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
{
"repository": "polymorfa/polymorfa",
"commit": "14153ad9d69ddd3bae972594e6b3dc3ddae8e8e4",
"commit": "a3db53e74c6e24507ca01e2ff6ecba19358422c7",
"releaseStatus": "source-only",
"sources": {
"messaging": {
"sourcePath": "apps/api/docs/openapi.json",
"sourceSha256": "44a2cc304483d7cd4e12974b8f31df92a3b7880d21152aa70af0a50948b40cb1",
"sourceSha256": "0c66f1ee93923cf57425ac29c01a84c5c140b703ace2160e1b899ee6dad0b071",
"paths": {
"/messaging/{session}/contacts/{contactId}/business-profile": {
"get": {
Expand Down Expand Up @@ -808,7 +808,7 @@
"whatsapp_group_suspended",
"whatsapp_group_has_no_participants",
"bansafe_suspended",
"bansafe_org_suspended",
"bansafe_team_suspended",
"bansafe_cold_blocked",
"bansafe_cold_held",
"bansafe_throttled",
Expand All @@ -831,7 +831,7 @@
"request_log_url": {
"type": "string",
"format": "uri",
"description": "Console page that shows this request. Returned only to organization and project credentials whose request was logged."
"description": "Console page that shows this request. Returned only to team and project credentials whose request was logged."
}
},
"required": ["type", "code", "message", "param", "request_id"]
Expand Down
Loading
Loading