Skip to content
← Public packages

@kody/zendesk

Call Zendesk tickets, users, and Help Center articles through OAuth or an API token.

FollowFork

Files

AGENTS.md

99 lines · 3.6 KB · Markdown

@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

LaneCredentialNotes
OAuth (recommended)integration zendesk or zendesk-<purpose>BYO Zendesk OAuth client
API token + emailsecrets zendeskApiUsername ({email}/token) + zendeskApiTokenFast 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

ExportImport
overviewkody:@kody/zendesk
accountskody:@kody/zendesk/accounts
configurekody:@kody/zendesk/configure
smoke-testkody:@kody/zendesk/smoke-test
mekody:@kody/zendesk/me
list/get/search/create/update ticketskody:@kody/zendesk/list-tickets (etc.)
list-ticket-comments / add-ticket-commentkody:@kody/zendesk/list-ticket-comments / .../add-ticket-comment
list/get/search/create/update userskody:@kody/zendesk/list-users (etc.)
list/get/search/create/update articleskody:@kody/zendesk/list-articles (etc.)
requestkody:@kody/zendesk/request
scheduled-account-healthkody:@kody/zendesk/scheduled-account-health
typeskody:@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-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.