@kody/zendesk
Call Zendesk tickets, users, and Help Center articles through OAuth or an API token.
Files
@kody/zendesk — agent notes
Human setup and intent live in 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-<purpose> | 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)
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):
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.
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-ticketsprefixestype:ticketwhen missing.- Creating an article needs Help Center
sectionId. - Helpers project slim objects; use
./requestfor extra fields. - Scopes:
tickets:read/write,users:read/write,hc:read/write, or broadread/write. 401/403 messages name the missing scope and next setup URL. - After fork, connect your Zendesk — do not treat live
@kody/zendeskpackage storage as yours. KeepdryRun/confirmguards. - Do not enable the
account-healthjob unless the operator asks.