@sendbird/cli 0.0.0-stage → 0.3.0-alpha.1

package/PROVENANCE.md

@@ -0,0 +1,15 @@
+# Implementation provenance
+
+This separate CLI follows the approved Sendbird Chat alpha scope. Its registry, runner and CLI are implemented here; Dashbird was inspected as an internal design reference for authentication, HTTP requests, profiles, JSON output, inventory auditing and agent distribution.
+
+- Dashbird reference checkout: `dashbird-cli-unified`, commit `11ddbd6` (local checkout, not a release claim).
+- Dashboard baseline: `f29b7c5cfcb87e67aa572f8c5fe9e9dda44fad31`.
+- Exact Dashboard file/symbol/line/hash mappings and discovered axios call sites are in `references/dashboard-inventory.json`.
+- API source and React form source were both inspected. Notable cases: Supergroup path switching, multipart channel/user bodies, metadata upsert, org creation returning `organizations[]`, session cookie names, support case Salesforce-style field names.
+- No Delight role bypass or generated Delight API surface is included.
+
+The first-party CLI is proprietary; see LICENSE. Dependency terms are preserved in NOTICE.md and the upstream packages. Reference repositories do not by themselves establish ownership or redistribution permission. Public distribution remains subject to rights and license review; earlier grants are not revoked by this notice.
+
+SDK extension (`0.2.0-alpha.1`): uses the official `@sendbird/chat` package pinned at 4.22.13, including its Node transport support. SDK method/type mappings are tracked separately in `references/sdk-commands.json`; they are not claimed as Dashboard API wrappers. The worker boundary isolates SDK background timers and keeps diagnostic logs out of CLI data output. [Official authentication](https://sendbird.com/docs/chat/sdk/v4/javascript/application/authenticating-a-user/authentication) and [message documentation](https://sendbird.com/docs/chat/sdk/v4/javascript/message/overview-message) were used alongside the installed declaration files.
+
+The Pro extension keeps SDK mappings separate from Dashboard HTTP provenance. `references/dashboard-inventory.json` records the current Dashboard revision, exact source symbols and hashes of the owned validation/normalization modules. Offline CI checks those hashes; a Dashboard source audit is still a separate check and neither proves deployed Gate routing nor live entitlement. No Bot/GDPR proxy route is inferred from the presence of an internal handler.

package/README.md

@@ -1,3 +1,458 @@
-# Temporary Holding Version
+# Sendbird CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Chat Dashboard operations for people and AI agents. **Validation alpha**: environment-bound CLI OAuth and in-memory reuse of existing Chat user tokens. Node.js 22.23.4+ (22.x) or 24.22.1+ (24.x), macOS/Linux, with native Windows support targeting Windows 11 x64 and PowerShell 7. See [Windows setup and validation limits](docs/windows.md).
+
+Proprietary software. See [LICENSE](LICENSE) for first-party terms and [NOTICE.md](NOTICE.md) for dependency notices. Repository visibility and package availability are managed separately.
+
+## Start here with an AI agent
+
+```sh
+sendbird --json agent
+sendbird --json commands --compact --search message send --transport sdk
+sendbird --json describe chat message send
+sendbird help chat message send
+sendbird --json workflows first-message
+```
+
+Bare `sendbird` returns the same small, offline guide. `agent`, `commands`,
+`describe`, and `workflows` never log in, read saved profiles, change configuration,
+or call the network. `commands --compact` is bounded and searchable (including
+common Korean intent words); multiword searches do not need shell quotes.
+Unfiltered `commands` retains the full catalog for existing consumers. `describe`
+includes exact flags, required inputs, credential type, constraints and a shell/argv
+dry-run template. Uppercase identifiers are placeholders, not guessed defaults.
+
+Errors now include structured `next` argv suggestions and an `outcome_unknown` indicator for uncertain mutations. SDK token failures do not tell agents to fix an unrelated Dashboard login. `auth status --summary` avoids dumping full organization settings.
+
+For staging SDK work:
+
+```sh
+sendbird --profile staging --app-id APP_ID chat sdk status \
+  --as-user USER_ID
+```
+
+With CLI OAuth, SDK commands discover the selected app's standard or Delight region hosts in the selected environment at execution time. The optional `app sdk-config --raw > sdk-config.json` file contains no credentials; pass it with `--sdk-config-file` to specify expected hosts. Automatically retrieved Chat tokens still require a matching authoritative Gate route on every execution. Explicit API/WebSocket host pairs remain available. Do not mix a config file with explicit host options. Workflow commands only print plans; conditional steps and resource creation still depend on the user's task and actual state.
+
+## Pro Chat operations
+
+The Pro extension covers indexed search, mentions, message meta arrays, thumbnail requests, translation preferences, Polls, blocking/reporting and weekly DND. Dashboard-role commands add moderation, filters, bounded announcements, analytics, Chat webhooks and Push administration. Sensitive SSO, IP and app deletion operations require extra target confirmations.
+
+Inspect the new offline workflow with `sendbird --json workflows pro-chat`, or open the Pro feature guide with `npm run docs`. Customer UI/offline behavior follows the selected native-plugin, temporary ZIP or no-assistance mode (or explicitly retained guide-only work). Command implementation is separate from live verification: Push devices/providers, an IdP, a callback receiver and account-specific entitlements must be tested independently. Bot/GDPR contracts remain open; Data Export is intentionally excluded. No application management API key fallback is provided.
+
+The supported Node release lines are 22.x and 24.x, with security floors of
+22.23.4 and 24.22.1 respectively. These include the
+[October 21, 2026 Node.js security fixes](https://nodejs.org/en/blog/vulnerability/october-2026-security-releases).
+Update the installed Node runtime as well as the CLI package. CI, publishing and
+source-audit jobs pin these patched versions.
+
+## Register the CLI Skill with your coding tool
+
+Installing the binary does not register its bundled Skill with Claude Code or Codex. From your project root, use one of:
+
+```sh
+sendbird skills install --agent claude --scope project
+sendbird skills install --agent codex --scope project
+sendbird skills status
+```
+
+Use `--scope user` for all your local projects. Project scope means the current directory: Claude Code uses `.claude/skills/sendbird`, Codex uses `.agents/skills/sendbird`; user scope uses the same paths under your home. Registration is offline, copies only the operational `sendbird` Skill and its references, and does not install a client plugin, hooks or the optional CLI-bootstrap Skill. Existing modified/unmanaged files and symlink search paths are refused. An unchanged CLI-managed copy can be refreshed with the same install command. Interrupted changes may retain a lock or backup; `skills status` reports these for manual review and never deletes them automatically.
+
+Use `--dry-run` to preview installation/removal. `sendbird skills show` prints the full bundled instructions and reference paths for an Agent that already found the binary. `sendbird --json skills show` provides those fields as JSON. Remove only an unchanged managed copy with `sendbird skills remove --agent claude --scope project --yes` (or `--agent codex`). Restart/reload your host if needed and verify the Skill appears. Status inspects local files only; installed host plugins, actual loading and automatic selection are not verified. Avoid registering a second copy when an installed plugin already supplies this Skill. Cloud/managed hosts may use different discovery or policy and are not verified by this local registration.
+
+## Browser documentation
+
+From the repository, run:
+
+```sh
+npm run docs
+```
+
+This builds the standalone documentation and opens it in your default browser.
+Keep the terminal running; press Ctrl+C to stop. The server binds only to localhost.
+
+- `npm run docs:build`: generate the static site in `.docs-site/`.
+- `npm run docs:serve`: serve the existing build and open the browser.
+- `npm run docs -- --no-open --port 4174`: choose a port or run without opening a browser.
+
+Guides live in `site/guides.ts`; command pages and options come directly from the CLI registry.
+Official-documentation-based tutorials live in `site/tutorials.ts`, with shared Bash setup in `site/tutorial-session.sh`. The **User scenario tutorials** section covers Open chat, distinct 1:1 chat/read/typing, files/threads/reactions, conditional invitations, public Supergroups, and message history/update/delete. Each includes source links, terminal roles, real response-ID chaining, checkpoints, cleanup and CLI limitations.
+The website, build tools and `docs/` development notes are **excluded from the npm bundle**.
+These commands require a repository checkout with development dependencies. The portable AI Skill remains in the CLI package.
+
+## Install and start
+
+From this repository:
+
+```sh
+npm ci
+npm run build
+npm link
+sendbird --help
+sendbird setup
+```
+
+For a portable installation, run `npm pack` and install the resulting `.tgz` with `npm install -g ./sendbird-cli-0.3.0-alpha.1.tgz`. Public npm availability is not assumed; this repository has not published the package.
+
+Explicit staging setup:
+
+```sh
+sendbird profile create --name staging --env staging
+sendbird profile use --name staging
+sendbird auth login
+sendbird org list
+sendbird org use --id ORG_UID
+sendbird app list
+sendbird app use --id APP_ID
+sendbird doctor
+```
+
+To leave a non-secret project marker that coding agents can discover in an
+existing repository, select an app and run:
+
+```sh
+sendbird --app-id APP_ID project init --yes
+```
+
+This creates a visible `sendbird.json` in the current directory with the app,
+organization, region, and an explicit first command for Agents:
+`sendbird --dry-run agent`. It contains no tokens, cookies, passwords, or API
+keys. Add `--project` to use this context for a command. It takes precedence
+over saved profile context, while explicit flags still win.
+This prevents a repository file from silently selecting the target of a remote
+request. Inspect the marker with `sendbird project status`.
+
+Run `sendbird profile` to see the effective profile and saved active profile.
+Remove an unused profile with `sendbird profile delete --name NAME --yes`;
+this also revokes its saved OAuth login.
+
+To undo saved selections without logging out, use `sendbird app clear` for
+the app only or `sendbird org clear` for the organization, app and region.
+Every command still needs a profile; `sendbird profile use --name prod` returns
+to the built-in default profile if it exists. Switching profiles does not
+erase the old profile's saved context.
+
+An account without an organization can use:
+
+```sh
+sendbird org create --organization-name 'My team'
+# Use the returned organizations[0].uid
+sendbird org use --id ORG_UID
+sendbird app create --app-name 'Chat demo' --region YOUR_REGION
+sendbird app use --id APP_ID
+```
+
+Choose a region actually available to your organization. Account signup and email verification remain in [Dashboard](https://dashboard.sendbird.com/auth/signup). The existing API determines whether an account can create another organization.
+
+## Operate Chat
+
+```sh
+sendbird chat user create --user-id alice --nickname Alice
+sendbird chat user create --user-id bob --nickname Bob
+sendbird chat channel create --type group --name Demo --user-ids '["alice","bob"]'
+sendbird chat channel create --type supergroup --name Community --user-ids '["alice","bob"]'
+sendbird chat channel create --type open --name Lobby
+sendbird chat channel list --type group --limit 20
+sendbird chat channel get --type group --id CHANNEL_URL
+sendbird chat channel members invite --type group --id CHANNEL_URL --user-ids '["charlie"]'
+sendbird chat user metadata set --id alice --metadata '{"tier":"free"}'
+sendbird chat channel delete --type group --id CHANNEL_URL --dry-run
+sendbird chat channel delete --type group --id CHANNEL_URL --yes
+```
+
+## Read usage and plans (BILL-01)
+
+These commands make **GET requests only**. Select the intended organization first;
+subscription and plan-catalog reads fail if it differs from the authenticated
+billing organization. The catalog also requires `organization.general.all`,
+matching Dashboard's Change control. Use `--json` for complete, redacted
+source values.
+
+```sh
+sendbird --profile staging --org-id ORG_UID usage chat org \
+  --start-month 2026-10 --end-month 2026-10
+sendbird --profile staging --org-id ORG_UID --app-id APP_ID usage chat app \
+  --target-month 2026-10
+sendbird --profile staging --org-id ORG_UID usage calls org
+sendbird --profile staging --org-id ORG_UID --app-id APP_ID usage calls app
+sendbird --profile staging --org-id ORG_UID --app-id APP_ID usage calls app-trend \
+  --resolution monthly --start 2026-09 --end 2026-10
+sendbird --profile staging --org-id ORG_UID usage calls trend \
+  --resolution daily --start 2026-10-01 --end 2026-10-06
+sendbird --profile staging --org-id ORG_UID billing plan current
+sendbird --profile staging --org-id ORG_UID billing plan list
+```
+
+Calls usage can contain Live totals; the human trend displays the Calls series,
+while `--json` retains all source series. Plan catalog entries do not certify
+eligibility or quote a charge. Upgrades, downgrades, card handling, vouchers,
+and other billing changes are not provided by BILL-01.
+
+## Prepare a Chat plan change (BILL-02)
+
+The CLI checks the selected organization, role, current/scheduled subscription,
+plan catalog and billing channel. **It does not submit a subscription change.**
+Gate currently has no authoritative quote endpoint for the final charge and
+activation date. Finish the purchase or downgrade in Dashboard, then re-read the
+subscription from the CLI. Card details are neither printed nor saved.
+
+```sh
+sendbird --profile staging --org-id ORG_UID billing plan check --plan plan_a_5k
+sendbird --profile staging --org-id ORG_UID billing plan change \
+  --plan plan_a_5k --confirm-org-name 'YOUR_ORGANIZATION_NAME' --yes
+# Open the returned Dashboard URL, check the organization, price and effective date,
+# then confirm the change there.
+sendbird --profile staging --org-id ORG_UID billing plan verify --plan plan_a_5k
+```
+
+`check`/`change` require `organization.general.all`. `change` also requires the
+exact organization name and `--yes` to prepare the handoff. The browser is not
+opened automatically. `verify` reports only `current`, `scheduled` or
+`not_reflected`; a matching plan is not proof that this CLI changed it.
+Sales/AWS contracts, Shopify, managed payment methods, legacy organizations and
+existing scheduled changes require Dashboard review. The catalog can include
+support or sales-only products, so presence alone is not purchase eligibility.
+`--dry-run` is offline and checks no live policy; use `check` for live reads.
+Agents must obtain explicit customer authorization before any paid change in
+Dashboard; a generic app-building request does not authorize a purchase.
+
+Every flag that accepts a boolean/number/array/object takes a JSON value (`false`, `20`, `'["alice"]'`). String flags take literal text. `--body-file request.json` or `--body-file -` accepts JSON; explicit field flags override file fields. Input is validated before HTTP calls. Unknown body fields are rejected.
+
+Commands are noninteractive except for `auth login`, `setup`, and terminal confirmation of Calls free trials (standalone or offered after Calls app creation/activation); staging OAuth opens a browser and waits for its loopback callback without needing a terminal prompt. The default stdout is a bounded, readable view. Add `--json` for machine-readable JSON (NDJSON for watch), or `--raw` for the legacy result body as JSON. `--human` remains an explicit alias for the default view. Prompts and errors go to stderr; errors become structured JSON with `--json`. `--profile`, `--org-id`, `--app-id` override saved context for one command. Choosing another organization clears the saved app; a one-off org override also drops a saved app from another org.
+
+## Output contract
+
+With `--json`, every executed Dashboard, SDK, and local operation writes one successful JSON envelope to stdout:
+
+```json
+{
+  "ok": true,
+  "command": "sendbird chat channel delete",
+  "effect": "mutation",
+  "status": "accepted",
+  "target": { "app_id": "APP_ID", "channel_url": "CHANNEL_URL" },
+  "result": {},
+  "response": "empty"
+}
+```
+
+`status` distinguishes `preview` (no request sent), `accepted` (mutation acknowledged, read back to confirm state), `verified` (read completed), and `completed` (stream ended). Local operations use `succeeded`. `target.actor_user_id` identifies the connected SDK user, separate from a resource's `user_id`. `result` preserves the normalized command result. `response: "empty"` means Sendbird accepted the operation without a response body; it is still a successful receipt, not missing stdout. The default view prints a bounded summary or table; dry-run previews include redacted request fields. `--raw` keeps the pre-envelope JSON result for existing scripts and config files, even without `--json`. `--response-schema --json` describes the machine envelope; for watch it includes both event lines and terminal completion. `sendbird --json describe COMMAND` also exposes `result_schema` for the inner value. SDK watch emits readable event lines by default and NDJSON with `--json`. Errors stay on stderr; `--json` errors include `ok: false`, `next`, and `outcome_unknown` for uncertain writes.
+
+Human receipts name the completed action and resource. Lists use light tables
+or full-ID cards, and detail views focus on fields needed for the next
+decision. `--no-color` and `NO_COLOR` disable color; pipes and `--json` are
+unstyled. Machine status `accepted` still means the mutation was acknowledged,
+not that another user received a message. The shared design and review rules
+are in [the human output contract](docs/human-output.md).
+
+Lists are bounded to 20 by default, maximum 100. Follow `next` using `--token` for Dashboard Chat lists, `--offset` for apps. SDK query lists use `--page` and return `next_page`. No hidden fetch-all operation is performed. An org-filtered app page may be empty while more pages remain. Because app list rows omit organization identity, filtering reads one app detail per row to verify ownership. If Gate lists an app whose detail says it no longer exists, that row is omitted and counted in `skipped_unavailable_applications`; other detail failures still stop the command.
+
+## Chat SDK: messages and live channel activity
+
+The CLI includes the official `@sendbird/chat` v4 SDK. SDK commands act as a Chat **user**. With CLI OAuth for the selected environment, `--as-user` reads the selected user’s existing access token through Gate and passes it directly to the SDK worker. The CLI never prints or saves it. Gate applies its existing `with_access_token` permission check. This access token remains valid until revoked, so it is not a short-lived session. If the user has no access token, issue one explicitly or choose `--allow-guest` only where app policy permits.
+
+```sh
+sendbird chat sdk status --app-id APP_ID --as-user alice
+sendbird chat message send --app-id APP_ID --as-user alice --type group --id CHANNEL_URL --message 'Hello'
+sendbird chat message list --app-id APP_ID --as-user alice --type group --id CHANNEL_URL --limit 20
+
+# Another terminal, using Bob's existing token in memory:
+sendbird chat channel watch --app-id APP_ID --as-user bob --type group --id CHANNEL_URL --seconds 60
+```
+
+For an external identity provider, explicit `--user-token-file` accepts a raw user token or JSON containing `access_token`/`session_token`. Optional `user_id` and `app_id` bindings must match. Only explicit `--allow-guest` permits tokenless SDK login, which can create a user depending on app policy. The CLI does not create token files automatically.
+
+Supported SDK operations:
+
+- `chat message send`, `file`, `list`, `get`, `update`, `delete`.
+- `chat message reply`, `thread`, `reaction add/remove`, `pin/unpin` (Group/Supergroup).
+- `chat message receipts` and `chat channel typing` (regular Group only).
+- `chat channel join`, `leave`, `invitation accept/decline`, `read` (Group/Supergroup).
+- `chat channel participants list` (Open; one bounded query page per invocation).
+- `chat sdk channel my list/unread`: connected-user Group/Supergroup pages and total unread messages. Open channels have no member-based "my channels" list. The list always includes channels lacking a last-message projection. Per-channel SDK unread snapshots can disagree with the aggregate; when the last message is absent, the snapshots are `null`. The CLI offers neither an unread-only nor an empty-channel exclusion filter.
+- `chat sdk user invitation get/set` and `chat sdk channel count-preference get/set`: automatic invitation acceptance and per-channel unread/mention count preferences.
+- `chat channel watch`: message, reaction, membership, read/delivery receipt and typing events supported by each channel type, as NDJSON. It does not mark messages as read automatically.
+- `chat sdk …`: connected-user member operations, counters, pins, push/snooze preferences, channel visibility/history, scheduled messages, Poll reads/votes, translation, change logs, and permission-gated operator/moderation actions.
+
+Use `--id` for the channel URL and `--message-id` for a message. Text sends can use `--parent-message-id` for replies. File messages accept exactly one of `--file` (local regular file, maximum 25 MiB) and `--file-url` (HTTPS). Access codes belong in private JSON body files, not CLI values. Open-channel SDK operations temporarily enter the channel and exit on completion; Group membership is never silently created when sending.
+
+Each SDK command makes a fresh connection and disconnects on completion. Typing/receipt and per-channel unread values are point-in-time snapshots, not a persistent app session. My-channel, participant, member, pinned-message, scheduled-message, and Poll lists accept one-based `--page N` (maximum 100); use `result.next_page` when present and keep the same limit/filter. SDK query cursors cannot survive a CLI process, so a later page replays earlier pages in that invocation. Cost grows with page number, and concurrent changes can shift results; this is not a stable export. History responses return `next_before_id`, used with `--before-id` to avoid skipping equal timestamps. Thread paging uses the SDK's inclusive timestamp interface (`--before`), so deduplicate message IDs; this is not a complete thread-export command.
+
+Scheduled-message lists include canceled history by default. Use `chat sdk message scheduled list --status pending` to see remaining sends and `--status canceled` to verify cancellation by `scheduled_message_id`. Canceling a schedule does not remove it from the all-status list. Snooze timestamps use Unix milliseconds; enabling requires both `--start-at` and `--end-at` with end after start. Disabling with `--enabled false` preserves the existing interval. Channel hide/history reset and scheduled send-now/cancel require `--yes`, as do operator/moderation changes.
+
+Staging profiles discover SDK hosts automatically for the selected app using CLI OAuth. `--sdk-config-file` or **both** `--sdk-api-host HTTPS_ORIGIN` and `--sdk-ws-host WSS_ORIGIN` bypass that lookup only with an explicit `--user-token-file` or `--allow-guest`. Automatic Chat-token retrieval always verifies the hosts against Gate metadata before reading the token. Without an explicit override or a successful lookup, staging never falls back to production hosts. SDK commands run in isolated workers: timeouts, Ctrl+C and completion clean up connections, handlers and SDK timers. `--timeout` defaults to 30 seconds; watch has its own bounded duration after readiness, and typing adds its requested duration to the operation budget. CLI code never resends a message automatically; SDK transport/reconnection behavior follows the official SDK. After an interrupted/timed-out write, read back before retrying.
+
+Run `npm run docs` and open **SDK chat and real-time events** for recipes, restrictions and authentication details. Friend administration and file scheduling are not yet implemented. Poll lifecycle, user blocking and weekly DND are implemented; inspect the Pro guide for verification boundaries. Real delivery requires a valid application, user tokens and channel access; mock tests do not prove live delivery.
+
+## Authentication and secrets
+
+For **staging**, `sendbird --profile staging auth login` now opens Gate's browser OAuth consent and returns automatically to the CLI. `--method oauth` selects it explicitly. It uses a separate CLI Bearer token, bound by Gate to the approving Dashboard session; it does not use a Chat application API token. Gate currently grants one broad `cli:dashboard` scope without an endpoint allowlist, so this is a staging integration only. The grant expires when its Dashboard session expires or is signed out. The CLI refreshes an expiring access token while that grant is valid, and `auth logout` revokes the saved access and refresh tokens. It **ignores** any Dashboard `Set-Cookie` returned to a Bearer request.
+
+Browser login uses the selected profile's Gate environment and requires Gate to enable/advertise its CLI OAuth client. Production internal smoke has been verified on a dedicated test app; other features and production policies still need their respective approvals. Email/password and cookie-import login have been removed. macOS stores OAuth credentials in Keychain; Linux uses Secret Service through `secret-tool` (`libsecret-tools`); Windows uses Credential Manager through the system Windows PowerShell host. If Secret Service is unavailable or locked, login reports that the session cannot be saved and fails; it does not fall back to a local credential file. Existing Linux session files are never read; remove them and log in again.
+
+For staging SSO/2FA, use `sendbird --profile staging auth login` and finish the normal browser login and consent. `auth logout` revokes the CLI grant; it does not sign out other Dashboard sessions.
+
+For a new account, `sendbird setup` can guide signup, organization selection or creation, region selection, and Chat app creation. At the end it reviews the profile/environment, organization, app and region, then asks whether to save them as defaults. Saving also makes that profile active. Skipping or cancelling keeps selection defaults unchanged; sign-in and created resources remain, and reauthentication may reset old account context. An existing app stays in its current region; the saved region is for future app creation. The result includes `defaults_saved` and a context-bound `next_argv` even when you skip saving. The equivalent explicit flow is:
+
+```sh
+sendbird --profile staging auth signup
+sendbird auth verify-email --token-file ./private-verification-link.txt
+sendbird org create --organization-name 'My team'
+sendbird org use --id ORG_UID
+sendbird org region list
+sendbird org region use --id REGION_ID
+sendbird app create --app-name 'Chat demo'
+sendbird app use --id APP_ID
+```
+
+`setup` offers sign-in or account creation in both production and staging when authentication is needed. `auth signup` opens the selected environment's Dashboard signup page with a Gate OAuth `next` URL. The person completes signup and terms acceptance in the browser, then approves CLI access. Gate redirects to the local CLI callback; setup continues with organization, region and app selection. Email verification remains a separate step. `org region use` saves an allowed region for later `app create`; it does not change an organization's available regions.
+
+Browser OAuth requires a person to approve the grant. Headless email/password and session-cookie imports are not supported. `SENDBIRD_CONFIG_DIR` isolates configuration and credential-store identity; `SENDBIRD_PROFILE` selects a default profile.
+
+Secret output paths inside a Git worktree must be ignored and untracked. Existing files, Git metadata, and unverifiable repositories are rejected before API requests. Symlink parents are checked at their physical destination; no force bypass is provided. This prevents accidental Git exposure at write time, not later forced adds or ignore-rule changes. Keep the destination directory private.
+
+Secret values are redacted from stdout, errors and previews. To receive a Chat user token, explicitly write to a **new** private file:
+
+```sh
+sendbird chat user token issue --id alice --yes --secret-output /private/path/outside-git/alice-token.json
+```
+
+Secret-output files contain the unredacted response. Existing files are never overwritten. Application API token listing, issuance and revocation are not supported by this CLI. CLI OAuth and Chat user tokens remain separate credentials.
+
+`app auth-policy get/set` uses Dashboard's `guest_user_policy`: `0` read/write, `1` read-only, `2` deny login for users without an access token. Changes require `--yes`.
+
+## AI use and support
+
+### Find and read CLI docs from the terminal
+
+`sendbird docs search "group chat"` searches a small, versioned guide/tutorial section index offline. Results include a stable section ID, source path, browser URL and exact `docs read` argv. Follow `next_offset` with `--offset` when needed; `--limit` is 1–20. Command flags and schemas remain available through `sendbird commands --compact --search WORDS` and `sendbird describe ...`.
+
+```sh
+sendbird docs search "message send" --limit 5
+sendbird docs read 'guide/sdk-chat#messages' --base-url http://127.0.0.1:4173
+```
+
+`docs read` fetches only the selected Markdown section from a matching docs build and checks its digest against the installed index. In a source checkout, start `npm run docs -- --no-open`; if it uses another port, supply `--base-url` or `SENDBIRD_DOCS_URL`. A hosted docs build must use HTTPS. Without an available matching server, search and command discovery still work offline; read returns a structured, actionable error. Each section is capped at 24 KB. The site and section content remain outside the npm package.
+
+Use the bundled [Sendbird skill](skills/sendbird/SKILL.md) and [setup prompt](docs/ai-onboarding.md). `sendbird --json agent`, `--json commands --compact --search`, and `--json describe` provide focused discovery; `COMMAND --example` and `COMMAND --response-schema` remain available without authentication. See the [command reference](references/commands.md).
+
+For customer app creation or edits, the Skill offers three choices: review official native-plugin installation information, explicitly run the client plugin once from a checksum-verified ZIP, or continue without client assistance. Installing Sendbird CLI does not itself install or invoke the client plugin. Selecting the ZIP route starts a separate authenticated Claude Code process on macOS/Linux; it prints the publisher notice to stderr before execution and permits editing only. The parent Agent reviews changes and performs installation/build/runtime checks. The Skill also shows a notice summary and the publisher's [What runs on your machine](https://github.com/sendbird/sendbird-client-plugin#what-runs-on-your-machine) link before installation/execution guidance. Emitting a notice is not proof of human visibility or consent. See [the mode contract](skills/sendbird/references/build-chat-app.md) and [ZIP execution](skills/sendbird/references/client-plugin-bridge.md). Guide-only work remains available when explicitly requested; an existing guide-only choice never becomes ZIP authorization. A failure never triggers another mode automatically.
+
+Technical Chat support is supported with `sendbird support ticket submit --body-file case.json --dry-run`. The body contains `Subject`, `Description`, `Development_Platform__c`, and optionally `Priority`, `SDK_Version__c`, `Steps_to_Reproduce__c`. The app is taken from context. Remove `--dry-run` only when intending to submit. Alpha excludes attachments and other support categories; server-side plan entitlements still apply.
+
+Exit codes: 0 success; 1 unexpected failure; 2 usage/validation/confirmation; 3 not found; 4 authentication/authorization; 5 conflict/context mismatch; 6 rate limit; 7 network/unknown outcome; 8 upstream/schema failure. Dashboard requests and CLI-level SDK operations are not automatically retried; the SDK controls its own transport/reconnection behavior. A timed-out mutation may have completed; inspect the resource before repeating it.
+
+## Development and verification
+
+```sh
+npm run typecheck
+npm test
+npm run build
+npm run check:package
+SENDBIRD_DASHBOARD_PATH=../sbdashboard npm run audit
+```
+
+After reviewing Dashboard changes, `npm run generate` refreshes the pinned source inventory, command reference and typed wrapper entrypoints. Source hashes include API, form validation and dynamic URL helpers. Generated artifacts ship in the package; users do not need a Dashboard checkout.
+
+`npm run release:gate:offline` checks local contracts and isolated tarball installation. `npm run release:gate` additionally requires source parity and an explicitly configured staging smoke run. See [validation instructions](docs/validation.md), [scope](docs/scope.md), and [implementation provenance](PROVENANCE.md). Passing local tests is **not** a live A–Z validation claim.
+
+## CI and npm releases
+
+`npm run ci` runs local checks, generated-reference validation, docs build and clean package installation. GitHub Actions validates macOS/Linux and focused native Windows contracts on Node 22.23.4/24.22.1 and produces a tested `npm-candidate` artifact. Version tags trigger a separate npm OIDC release workflow; alpha/beta/rc versions publish to their own channels. Publication requires repository metadata, an approved license, npm scope access and trusted-publisher setup.
+
+See [`docs/releasing.md`](docs/releasing.md) in the source repository for first publication, branch/environment setup, version bumps and recovery. This development guide and the docs site are not bundled in the npm package.
+
+### Calls settings (CALLS-01)
+
+`calls settings general|webhook|chat-integration get/set` manages Dashboard Calls settings.
+`calls credits list --org-id ORG_UID` reads voucher history with status, start/expiry and balance. An expired voucher's balance does not prove usable credit. For an eligible self-service OWNER with no voucher history, `calls credits claim-trial --org-id ORG_UID --yes` requests the organization's one-time free Calls trial. Without `--yes`, an interactive terminal asks for confirmation (default No), showing the profile, environment and organization UID. JSON/raw output and non-interactive execution require `--yes`. Preview with `--dry-run` (no prompt or `--yes` needed). Activation never claims it automatically. Developer plans are blocked. Grant duration can follow the remaining Chat trial period, so inspect the returned expiry. Grant amount/duration are server-defined; no paid purchase or subscription change is requested. A failed claim may have created a voucher before activation failed, so inspect the list before any recovery and never automatically retry.
+
+For Direct calls, `--relay-method 'stun&turn'` tries P2P/STUN first and falls back to TURN; `--relay-method turn` uses server relay only. Direct-call cloud recording prevents relay changes. These meanings are also in help, `describe`, and response schemas.
+
+`calls settings push get` reads Calls activation and the shared Push switch without changing it.
+`calls activate --org-id ORG_UID --app-id APP_ID --yes` registers Calls on an existing app in its current region. It requires `organization.applications.all`; Gate enforces eligibility and regional availability. Read the activation state first. Registration includes independent app-state readback. After confirmed activation, eligible human terminals offer a separate free-trial confirmation (default No). Existing voucher history skips the offer. `--yes` alone is not credit consent.
+
+To create/activate and request the organization's one-time trial in one invocation, explicitly add `--claim-trial`:
+
+```sh
+sendbird --profile staging --org-id ORG_UID app create --app-name 'Calls demo' --region REGION --is-calls-enabled true --claim-trial --yes
+sendbird --profile staging --org-id ORG_UID --app-id APP_ID calls activate --claim-trial --yes
+```
+
+These are alternative paths (new or existing app). `--no-claim-trial` skips both the offer and request. JSON/raw and non-TTY execution never prompt or claim without `--claim-trial`. `--dry-run --claim-trial` previews both steps without requests or prompts. The trial requires confirmed activation and the same eligibility checks as the standalone command; existing voucher history, including expired/depleted vouchers, is skipped.
+
+An attempted/offered follow-up appears separately in `result.calls_trial` (`--raw`: `calls_trial`), with `status` = `accepted`, `skipped`, `declined`, or `failed`. Primary success keeps its normal exit code and receipt even when credits fail; agents must inspect this field as well as the primary `ok`. Accepted trial details are in `calls_trial.result.voucher` and `calls_trial.result.readback`. Never repeat app creation/activation to recover a credit failure: inspect `calls credits list`, then use the standalone command only if a new request is appropriate and authorized. This is not an atomic transaction, and no paid credits are purchased.
+
+`calls push list/create/update/delete --push-type apns_voip|calls_apns_remote|fcm_voip|huawei_voip` manages VoIP credentials.
+All writes require `--yes`; `--dry-run` makes no API calls. Webhook URLs, APNs passwords,
+and Huawei secrets use `--body-file` (or stdin). APNs/FCM uploads use `--credential-file`; same-format APNs metadata updates may reuse the existing certificate.
+Credential bytes are not saved in CLI configuration. Acknowledged writes include readback
+state; failed readback never causes an automatic repeated write. Actual calling, rooms,
+call history and credit purchases remain outside this scope.
+See the locally built **Calls settings** guide for private input examples and verification limits.
+
+Local/interactive commands that do not implement previews reject `--dry-run`
+before credential access, network requests or settings writes. Inspect them with
+`--help` or `--example` instead. This also applies to network reads such as
+`auth status` and `doctor`, whose authentication may refresh a grant. Email
+verification previews do not read private token files or prompt. SDK list replay is capped at page 100; a null
+`next_page` with `has_more=true` signals the ceiling, not the end of the dataset.
+Translation results include the language-keyed `translations` field.
+
+## Agent plugin and guided onboarding
+
+The plugin contains the operational `sendbird` Skill and the `sendbird-setup` onboarding Skill. It is CLI-first, with no hosted MCP server or automatic install hooks. [Claude Code prompt](onboarding/claude-code.md) and [Codex prompt](onboarding/codex.md) guide installation, browser approval, existing org/app selection, a choice to save defaults, optional authorized Chat practice and an explicit customer-code handoff.
+
+```sh
+# Shared marketplace (requires access and a published catalog).
+claude plugin marketplace add sendbird/sendbird-plugins
+claude plugin install sendbird-cli@sendbird
+# Or:
+codex plugin marketplace add sendbird/sendbird-plugins
+codex plugin add sendbird-cli@sendbird
+```
+
+For a private/local alpha, choose a new output directory. Its isolated
+`sendbird-cli-local` catalog can coexist with the shared marketplace:
+
+```sh
+npm run plugins:build -- /absolute/new-marketplace
+claude plugin marketplace add /absolute/new-marketplace
+claude plugin install sendbird-cli@sendbird-cli-local
+# Or:
+codex plugin marketplace add /absolute/new-marketplace
+codex plugin add sendbird-cli@sendbird-cli-local
+```
+
+Start a new session and invoke `/sendbird-cli:sendbird-setup` in Claude Code or `$sendbird-cli:sendbird-setup` in Codex. Its dependency-free installer verifies the CLI version and command capabilities, uses a checksummed bundled tarball when supplied, and supports npm or an isolated build of the trusted source checkout. It does not change shell rc files, overwrite an unmanaged executable, authenticate, or mutate remote resources. Use its returned executable to avoid an old npm link.
+
+The `sendbird` marketplace is maintained only in `sendbird/sendbird-plugins`, where one shared `.claude-plugin/marketplace.json` catalog provides entries for `sendbird-cli` and `sendbird-client` that both hosts read. This repository provides the CLI plugin manifests and skills, without a repository marketplace catalog. Shared catalog publication and access are prerequisites; this is not a listing in either host's public directory. See [marketplace migration and release coordination](docs/plugin-marketplace.md). The CLI npm package is not assumed published. Ordinary SDK practice keeps user tokens in memory; application API token management remains excluded. Customer-app work follows the person's selected mode: native plugin information/use, temporary ZIP execution with a pre-execution notice, or no client assistance. Native installation stays in the official host flow. Explicitly requested guide-only work remains in the current conversation; it never silently switches to ZIP execution.
+
+### Application features
+
+Read Dashboard feature activation snapshots with `sendbird app feature list`. Preview a change with `sendbird app feature set --feature poll --enabled true --dry-run`, then use `--yes` within the authorized org/app. These commands do not purchase or change a plan; usage charges may apply under the current subscription. Inspect `readback.status` and read the current settings before retrying. Data Export is excluded. See the generated `app-features` guide for filter coupling and Message Search migration restrictions.
+
+For source coverage, command execution evidence, the 100% target and worker/native boundaries, see [testing contracts](docs/testing.md).
+
+### Interpreting account and app output
+
+`auth status` shows the server-reported role and up to 12 distinct permission entries; use `--json` for the complete list. An absent permission list is unknown, not an empty grant. Organization identifiers are labeled **Organization UID** in human output; JSON keys and `--org-id` remain unchanged.
+
+`app get` labels Supergroup, Reactions and Poll as reported enabled/disabled or not reported. These come from `current_premium_features`, a plan snapshot, and do not establish runtime support or denial. `describe app get` and its response schema explain the same boundary for agents. For a Supergroup creation rejection with code 400108, use the returned context-bound `doctor` command to inspect prerequisites; do not infer the cause from the code alone or automatically change roles/features.
+
+The setup Skill asks whether to save the selected org/app in the profile; making a profile globally active is a separate choice. It offers Chat practice only as an optional next step. Setup alone does not authorize creating test users/channels or sending messages. A prior explicit choice/authorization is reused.
+
+### Understanding numeric response values
+
+Human output labels verified enum values, for example `Token required (2)` or
+`Detect only (3)`. JSON and raw responses retain their original numbers. Agents
+can read the meanings without credentials or network access:
+
+```sh
+sendbird --json describe app auth-policy get
+sendbird chat settings get --response-schema --json
+```
+
+Read `value_semantics.fields` in `describe`, or `x-sendbird-value-semantics` in
+response schemas. Paths are relative to `result`; original API fields are at the response root with `--raw`, which omits CLI-added `readback` fields;
+`*` means an array item. Unknown codes remain unknown. Meaning metadata does not
+expand writable inputs or prove effective permissions.

package/dist/acl.d.ts

@@ -0,0 +1,2 @@
+/** Dashboard levels are hierarchical only inside the same permission namespace. */
+export declare function permissionMatches(granted: string, required: string): boolean;

package/dist/acl.js

@@ -0,0 +1,12 @@
+/** Dashboard levels are hierarchical only inside the same permission namespace. */
+export function permissionMatches(granted, required) {
+    if (granted === required)
+        return true;
+    const g = granted.split("."), r = required.split("."), levels = ["view", "chat", "moderate", "all"];
+    if (g.length !== r.length ||
+        g.slice(0, -1).join(".") !== r.slice(0, -1).join("."))
+        return false;
+    const gi = levels.indexOf(g.at(-1)), ri = levels.indexOf(r.at(-1));
+    return gi >= 0 && ri >= 0 && gi >= ri;
+}
+//# sourceMappingURL=acl.js.map

package/dist/acl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acl.js","sourceRoot":"","sources":["../src/acl.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,QAAgB;IACjE,IAAI,OAAO,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACtC,MAAM,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,EAC1B,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,EACvB,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC,CAAC;IAC/C,IACE,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QACrB,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QAErD,OAAO,KAAK,CAAC;IACf,MAAM,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,EAClC,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC;IACjC,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;AACxC,CAAC"}

package/dist/billing-plan.d.ts

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { type Transport } from "./core.js";
+export declare const billingVerificationSchema: z.ZodObject<{
+    change_state: z.ZodEnum<{
+        scheduled: "scheduled";
+        current: "current";
+        not_reflected: "not_reflected";
+    }>;
+    product: z.ZodLiteral<"CHAT">;
+    requested_plan: z.ZodString;
+    mutation_sent: z.ZodLiteral<false>;
+    current_subscription: z.ZodNullable<z.ZodObject<{
+        subscription_name: z.ZodString;
+        apply_date: z.ZodNullable<z.ZodString>;
+        next_billing_date: z.ZodNullable<z.ZodString>;
+        end_date: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    future_subscription: z.ZodNullable<z.ZodObject<{
+        subscription_name: z.ZodString;
+        apply_date: z.ZodNullable<z.ZodString>;
+        next_billing_date: z.ZodNullable<z.ZodString>;
+        end_date: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    next: z.ZodString;
+    next_argv: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export declare const billingHandoffSchema: z.ZodObject<{
+    organization: z.ZodObject<{
+        uid: z.ZodString;
+        name: z.ZodString;
+    }, z.core.$strip>;
+    selection_state: z.ZodEnum<{
+        requires_dashboard_review: "requires_dashboard_review";
+        catalog_candidate: "catalog_candidate";
+    }>;
+    reasons: z.ZodArray<z.ZodString>;
+    payment_method: z.ZodString;
+    card_present: z.ZodNullable<z.ZodBoolean>;
+    quote: z.ZodNull;
+    effective_at: z.ZodNull;
+    change_completed: z.ZodLiteral<false>;
+    handoff: z.ZodObject<{
+        url: z.ZodString;
+        required: z.ZodLiteral<true>;
+        instruction: z.ZodString;
+    }, z.core.$strip>;
+    product: z.ZodLiteral<"CHAT">;
+    requested_plan: z.ZodString;
+    mutation_sent: z.ZodLiteral<false>;
+    current_subscription: z.ZodNullable<z.ZodObject<{
+        subscription_name: z.ZodString;
+        apply_date: z.ZodNullable<z.ZodString>;
+        next_billing_date: z.ZodNullable<z.ZodString>;
+        end_date: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    future_subscription: z.ZodNullable<z.ZodObject<{
+        subscription_name: z.ZodString;
+        apply_date: z.ZodNullable<z.ZodString>;
+        next_billing_date: z.ZodNullable<z.ZodString>;
+        end_date: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    next: z.ZodString;
+    next_argv: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/** No quote contract exists in Gate. These commands prepare a web handoff;
+ * they never submit subscribe, start a trial, or collect payment credentials.
+ * runner.ts verifies the authenticated organization and role before calling. */
+export declare function billingPlan(command: string, input: Record<string, unknown>, orgId: string, t: Transport, profileName?: string): Promise<unknown>;