# @kody/zendesk — agent notes Human setup and intent live in [`README.md`](./README.md). This file is for agents: imports, smoke/dryRun execute snippets, and edge cases. Secrets by **name** only — never paste token values. Do not disable live webhooks or jobs (the `account-health` job stays **disabled by default** unless an operator explicitly enables it). ## Auth / secrets / integrations | Lane | Credential | Notes | | --- | --- | --- | | OAuth (recommended) | integration `zendesk` or `zendesk-` | BYO Zendesk OAuth client | | API token + email | secrets `zendeskApiUsername` (`{email}/token`) + `zendeskApiToken` | Fast single-account lane | Subdomain is required (`acme` from `https://acme.zendesk.com`). Pass `subdomain` on each call, or store once with `./configure` into **this** package copy's `packageStorage`. Host: `{subdomain}.zendesk.com`. Multi-account: `account: 'work'` → `zendesk-work`; `integrationName: 'zendesk-work'`; API-token overrides via `secretName` / `usernameSecretName`. Optional `auth: 'oauth' | 'apiToken'`. ## Import paths | Export | Import | | --- | --- | | overview | `kody:@kody/zendesk` | | accounts | `kody:@kody/zendesk/accounts` | | configure | `kody:@kody/zendesk/configure` | | smoke-test | `kody:@kody/zendesk/smoke-test` | | me | `kody:@kody/zendesk/me` | | list/get/search/create/update tickets | `kody:@kody/zendesk/list-tickets` (etc.) | | list-ticket-comments / add-ticket-comment | `kody:@kody/zendesk/list-ticket-comments` / `.../add-ticket-comment` | | list/get/search/create/update users | `kody:@kody/zendesk/list-users` (etc.) | | list/get/search/create/update articles | `kody:@kody/zendesk/list-articles` (etc.) | | request | `kody:@kody/zendesk/request` | | scheduled-account-health | `kody:@kody/zendesk/scheduled-account-health` | | types | `kody:@kody/zendesk/types` | Also: `./tickets`, `./users`, `./articles` re-export list helpers. Prefer static `kody:@kody/zendesk/...` imports from `execute`. Do not lead with `packages.invoke`. ## Smoke test (read-only) ```ts import smokeTest from 'kody:@kody/zendesk/smoke-test' export default async function main() { return await smokeTest() // without creds => { ok: true, live: false, setup URLs } // with OAuth/token + subdomain => { live: true, hasUserId } (no email) } ``` Store subdomain (fork first — never write into live `@kody/zendesk`): ```ts import configure from 'kody:@kody/zendesk/configure' export default async function main() { return await configure({ subdomain: 'acme', email: 'agent@example.com', }) } ``` ## dryRun / confirm Mutating helpers require `confirm: true`. Pass `dryRun: true` to inspect the REST payload without calling Zendesk. `./request` treats GET and search paths as read-only; POST / PUT / PATCH / DELETE need confirmation. ```ts import createTicket from 'kody:@kody/zendesk/create-ticket' export default async function main() { return await createTicket({ subject: 'Follow up on onboarding', comment: 'Customer asked for a status update.', subdomain: 'acme', dryRun: true, }) } ``` ## Edge cases / fork notes - REST base: `https://{subdomain}.zendesk.com/api/v2`. - `./search-tickets` prefixes `type:ticket` when missing. - Creating an article needs Help Center `sectionId`. - Helpers project slim objects; use `./request` for extra fields. - Scopes: `tickets:read/write`, `users:read/write`, `hc:read/write`, or broad `read` / `write`. 401/403 messages name the missing scope and next setup URL. - After fork, connect **your** Zendesk — do not treat live `@kody/zendesk` package storage as yours. Keep `dryRun` / `confirm` guards. - Do **not** enable the `account-health` job unless the operator asks.