{"version":3,"sources":["../src/index.ts","../src/http/errors.ts","../src/regions/endpoints.ts","../src/regions/resolver.ts","../src/http/parse-error.ts","../src/auth/scopes.ts","../src/http/client.ts","../src/auth/pkce.ts","../src/auth/oauth-client.ts","../src/auth/management-session.ts","../src/cma/pagination.ts","../src/cma/assets.ts","../src/cma/base-client.ts","../src/cma/audit-log.ts","../src/cma/auth.ts","../src/cma/branch-aliases.ts","../src/cma/branches.ts","../src/cma/bulk.ts","../src/cma/content-types.ts","../src/cma/entries.ts","../src/cma/environments.ts","../src/cma/extensions.ts","../src/cma/global-fields.ts","../src/cma/labels.ts","../src/cma/locales.ts","../src/cma/publish-rules.ts","../src/cma/releases.ts","../src/cma/roles.ts","../src/cma/taxonomies.ts","../src/cma/tokens.ts","../src/cma/webhooks.ts","../src/cma/workflows.ts","../src/cma/client.ts","../src/cma/request-builders.ts","../src/images/builder.ts","../src/rte/to-html.ts","../src/rte/utils.ts","../src/rte/serializer.ts","../src/rte/to-markdown.ts","../src/rte/to-plaintext.ts","../src/rte/from-html.ts","../src/rte/transform.ts","../src/rte/validate.ts","../src/launch/response.ts","../src/launch/deployments.ts","../src/launch/environments.ts","../src/launch/projects.ts","../src/launch/client.ts","../src/launch/utils.ts","../src/brandkit/brand-kits.ts","../src/brandkit/voice-profiles.ts","../src/brandkit/client.ts","../src/knowledge-vault/items.ts","../src/knowledge-vault/client.ts","../src/generative-ai/client.ts","../src/developer-hub/response.ts","../src/developer-hub/apps.ts","../src/developer-hub/authorizations.ts","../src/developer-hub/hosting.ts","../src/developer-hub/installations.ts","../src/developer-hub/oauth.ts","../src/developer-hub/requests.ts","../src/developer-hub/client.ts"],"sourcesContent":["export * from \"./regions/index.js\"\nexport * from \"./http/index.js\"\nexport * from \"./auth/index.js\"\nexport * from \"./cma/index.js\"\nexport * from \"./images/index.js\"\nexport * from \"./rte/index.js\"\nexport * from \"./launch/index.js\"\nexport * from \"./brandkit/index.js\"\nexport * from \"./knowledge-vault/index.js\"\nexport * from \"./generative-ai/index.js\"\nexport * from \"./developer-hub/index.js\"\n","/**\n * Base error class for all Contentstack SDK errors.\n * Every error includes an actionable message and relevant context.\n */\nexport class ContentstackError extends Error {\n override readonly name: string = \"ContentstackError\"\n readonly status?: number\n readonly errorCode?: number\n readonly errors?: Record\n readonly requestPath?: string\n\n constructor(\n message: string,\n options?: {\n status?: number\n errorCode?: number\n errors?: Record\n requestPath?: string\n cause?: Error\n },\n ) {\n super(message, options?.cause ? { cause: options.cause } : undefined)\n this.status = options?.status\n this.errorCode = options?.errorCode\n this.errors = options?.errors\n this.requestPath = options?.requestPath\n }\n}\n\nexport class ContentstackAuthError extends ContentstackError {\n override readonly name = \"ContentstackAuthError\"\n override readonly status = 401\n}\n\nexport class ContentstackForbiddenError extends ContentstackError {\n override readonly name = \"ContentstackForbiddenError\"\n override readonly status = 403\n}\n\nexport class ContentstackNotFoundError extends ContentstackError {\n override readonly name = \"ContentstackNotFoundError\"\n override readonly status = 404\n}\n\nexport class ContentstackValidationError extends ContentstackError {\n override readonly name = \"ContentstackValidationError\"\n override readonly status: number\n\n constructor(\n message: string,\n options?: {\n status?: number\n errorCode?: number\n errors?: Record\n requestPath?: string\n cause?: Error\n },\n ) {\n super(message, options)\n this.status = options?.status ?? 400\n }\n}\n\nexport class ContentstackInvalidApiKeyError extends ContentstackError {\n override readonly name = \"ContentstackInvalidApiKeyError\"\n override readonly status = 412\n}\n\nexport class ContentstackRateLimitError extends ContentstackError {\n override readonly name = \"ContentstackRateLimitError\"\n override readonly status = 429\n readonly retryAfter?: number\n\n constructor(\n message: string,\n options?: {\n errorCode?: number\n errors?: Record\n requestPath?: string\n cause?: Error\n retryAfter?: number\n },\n ) {\n super(message, { ...options, status: 429 })\n this.retryAfter = options?.retryAfter\n }\n}\n\nexport class ContentstackServerError extends ContentstackError {\n override readonly name = \"ContentstackServerError\"\n}\n\nexport class ContentstackConfigError extends ContentstackError {\n override readonly name = \"ContentstackConfigError\"\n}\n","import {\n type ContentstackEndpoints as UpstreamEndpoints,\n getContentstackEndpoints,\n getRegionForString,\n} from \"@timbenniks/contentstack-endpoints\"\nimport type { ContentstackEndpoints, ContentstackRegion } from \"./resolver.js\"\n\n/** Brand Kit endpoints not available in upstream package — maintained locally */\nconst BRAND_KIT_URLS: Record = {\n us: {\n brandKit: \"https://brand-kits-api.contentstack.com\",\n brandKitAI: \"https://ai.contentstack.com/brand-kits\",\n },\n eu: {\n brandKit: \"https://eu-brand-kits-api.contentstack.com\",\n brandKitAI: \"https://eu-ai.contentstack.com/brand-kits\",\n },\n au: {\n brandKit: \"https://au-brand-kits-api.contentstack.com\",\n brandKitAI: \"https://au-ai.contentstack.com/brand-kits\",\n },\n \"azure-na\": {\n brandKit: \"https://azure-na-brand-kits-api.contentstack.com\",\n brandKitAI: \"https://azure-na-ai.contentstack.com/brand-kits\",\n },\n \"azure-eu\": {\n brandKit: \"https://azure-eu-brand-kits-api.contentstack.com\",\n brandKitAI: \"https://azure-eu-ai.contentstack.com/brand-kits\",\n },\n \"gcp-na\": {\n brandKit: \"https://gcp-na-brand-kits-api.contentstack.com\",\n brandKitAI: \"https://gcp-na-ai.contentstack.com/brand-kits\",\n },\n \"gcp-eu\": {\n brandKit: \"https://gcp-eu-brand-kits-api.contentstack.com\",\n brandKitAI: \"https://gcp-eu-ai.contentstack.com/brand-kits\",\n },\n}\n\nfunction mapEndpoints(\n upstream: UpstreamEndpoints,\n region: ContentstackRegion,\n hostsOnly: boolean,\n): ContentstackEndpoints {\n const bk = BRAND_KIT_URLS[region]\n const stripProtocol = (url: string) => url.replace(/^https?:\\/\\//, \"\")\n\n return Object.freeze({\n cma: upstream.contentManagement ?? \"\",\n cda: upstream.contentDelivery ?? \"\",\n graphql: upstream.graphqlDelivery ?? \"\",\n images: upstream.images ?? \"\",\n app: upstream.application ?? \"\",\n preview: upstream.preview ?? \"\",\n graphqlPreview: upstream.graphqlPreview ?? \"\",\n launch: upstream.launch ?? \"\",\n personalizeEdge: upstream.personalizeEdge ?? \"\",\n brandKit: hostsOnly ? stripProtocol(bk.brandKit) : bk.brandKit,\n brandKitAI: hostsOnly ? stripProtocol(bk.brandKitAI) : bk.brandKitAI,\n developerHub: hostsOnly\n ? stripProtocol(upstream.developerHub ?? \"\")\n : (upstream.developerHub ?? \"\"),\n })\n}\n\nconst ALL_REGIONS: ContentstackRegion[] = [\n \"us\",\n \"eu\",\n \"au\",\n \"azure-na\",\n \"azure-eu\",\n \"gcp-na\",\n \"gcp-eu\",\n]\n\nfunction buildEndpointMap(): Record {\n const map = {} as Record\n for (const region of ALL_REGIONS) {\n map[region] = mapEndpoints(getContentstackEndpoints(region), region, false)\n }\n return Object.freeze(map)\n}\n\nfunction buildHostMap(): Record {\n const map = {} as Record\n for (const region of ALL_REGIONS) {\n map[region] = mapEndpoints(getContentstackEndpoints(region, true), region, true)\n }\n return Object.freeze(map)\n}\n\nexport const ENDPOINT_MAP = buildEndpointMap()\nexport const HOST_MAP = buildHostMap()\n\n/** Check if a string is a valid region via the upstream package */\nexport function isValidRegion(input: string): boolean {\n return getRegionForString(input) !== undefined\n}\n\n/** Map of extra aliases our SDK supports beyond what the upstream package handles */\nexport const EXTRA_ALIASES: Record = {\n \"north-america\": \"us\",\n europe: \"eu\",\n australia: \"au\",\n}\n","import { ContentstackConfigError } from \"../http/errors.js\"\nimport { ENDPOINT_MAP, EXTRA_ALIASES, HOST_MAP, isValidRegion } from \"./endpoints.js\"\n\n/** All 7 Contentstack regions */\nexport type ContentstackRegion = \"us\" | \"eu\" | \"au\" | \"azure-na\" | \"azure-eu\" | \"gcp-na\" | \"gcp-eu\"\n\n/** Resolved endpoint URLs for a region */\nexport interface ContentstackEndpoints {\n /** CMA base URL, e.g. \"https://api.contentstack.io\" */\n cma: string\n /** CDA REST base URL, e.g. \"https://cdn.contentstack.io\" */\n cda: string\n /** GraphQL CDA endpoint */\n graphql: string\n /** Asset/image delivery base URL */\n images: string\n /** Application URL (for OAuth), e.g. \"https://app.contentstack.com\" */\n app: string\n /** Preview API base URL */\n preview: string\n /** GraphQL preview endpoint */\n graphqlPreview: string\n /** Launch API base URL */\n launch: string\n /** Personalize edge endpoint */\n personalizeEdge: string\n /** Brand Kit Management API base URL */\n brandKit: string\n /** Brand Kit GenAI and Knowledge Vault base URL */\n brandKitAI: string\n /** Developer Hub (Marketplace) API base URL */\n developerHub: string\n}\n\nconst VALID_REGIONS = new Set(Object.keys(ENDPOINT_MAP))\n\n/**\n * Resolve all API endpoints for a Contentstack region.\n *\n * @example\n * ```ts\n * const endpoints = resolveEndpoints(\"eu\");\n * // endpoints.cma === \"https://eu-api.contentstack.com\"\n * // endpoints.app === \"https://eu-app.contentstack.com\"\n * ```\n */\nexport function resolveEndpoints(region: ContentstackRegion): ContentstackEndpoints {\n return ENDPOINT_MAP[region]\n}\n\n/**\n * Resolve endpoints with https:// stripped (for SDK host parameters).\n *\n * @example\n * ```ts\n * const hosts = resolveHosts(\"eu\");\n * // hosts.cda === \"eu-cdn.contentstack.com\"\n * ```\n */\nexport function resolveHosts(region: ContentstackRegion): ContentstackEndpoints {\n return HOST_MAP[region]\n}\n\n/**\n * Normalize region aliases: \"na\" → \"us\", \"NA\" → \"us\", etc.\n * Case-insensitive. Throws ContentstackConfigError for unknown regions.\n */\nexport function normalizeRegion(input: string): ContentstackRegion {\n const lower = input.toLowerCase().trim()\n\n if (VALID_REGIONS.has(lower)) {\n return lower as ContentstackRegion\n }\n\n // Check extra aliases our SDK supports (north-america, europe, australia)\n const extraAlias = EXTRA_ALIASES[lower]\n if (extraAlias) {\n return extraAlias\n }\n\n // Check aliases handled by the upstream package (na, us, aws-na, etc.)\n if (isValidRegion(lower)) {\n // The upstream package recognized it — map back to our canonical region\n // \"na\" and \"us\" both map to the NA region which we call \"us\"\n if (lower === \"na\" || lower === \"aws-na\" || lower === \"aws_na\") return \"us\"\n if (lower === \"aws-eu\" || lower === \"aws_eu\") return \"eu\"\n if (lower === \"aws-au\" || lower === \"aws_au\") return \"au\"\n if (lower === \"azure_na\") return \"azure-na\"\n if (lower === \"azure_eu\") return \"azure-eu\"\n if (lower === \"gcp_na\") return \"gcp-na\"\n if (lower === \"gcp_eu\") return \"gcp-eu\"\n }\n\n const validRegions = [...VALID_REGIONS].join(\", \")\n const validAliases = [...Object.keys(EXTRA_ALIASES), \"na\", \"aws-na\", \"aws-eu\", \"aws-au\"].join(\n \", \",\n )\n throw new ContentstackConfigError(\n `Unknown region \"${input}\". Valid regions: ${validRegions}. Aliases: ${validAliases}.`,\n )\n}\n\nexport { ContentstackConfigError }\n","import { ContentstackError } from \"./errors.js\"\n\n/**\n * Parse a non-ok fetch Response into a ContentstackError.\n *\n * Handles the Contentstack API error format (error_message, error_code, errors)\n * and falls back to the HTTP status text when the body is not parseable.\n *\n * This is a shared utility used by React hooks and Vue composables to avoid\n * duplicating error-parsing logic across frameworks.\n */\nexport async function parseErrorResponse(\n response: Response,\n path: string,\n): Promise {\n try {\n const body = await response.json()\n return new ContentstackError(body.error_message ?? body.message ?? response.statusText, {\n status: response.status,\n errorCode: body.error_code,\n errors: body.errors,\n requestPath: path,\n })\n } catch {\n return new ContentstackError(response.statusText, {\n status: response.status,\n requestPath: path,\n })\n }\n}\n","/**\n * All available Contentstack OAuth scopes.\n *\n * Sourced from the Developer Hub API (`/manifests/oauth/scopes` endpoint).\n *\n * Use `OAUTH_SCOPE_DESCRIPTIONS` for human-readable explanations of each scope.\n * Use `OAUTH_SCOPE_PRESETS` for common scope combinations.\n *\n * @see https://www.contentstack.com/docs/developers/developer-hub/oauth-scopes\n */\nexport type ContentstackOAuthScope =\n // ── Developer Hub (Apps) ────────────────────────────────────────────\n | \"app.manifests:read\"\n | \"app.manifest:read\"\n | \"app.manifest:write\"\n | \"app.hosting:read\"\n | \"app.hosting:write\"\n | \"app.installations:read\"\n | \"app.installations.management:read\"\n | \"app.installations.management:write\"\n | \"app.authorizations:manage\"\n | \"app.authorizations.management:write\"\n | \"app.requests:write\"\n | \"app.requests.management:write\"\n\n // ── SCIM ────────────────────────────────────────────────────────────\n | \"scim:manage\"\n\n // ── User ────────────────────────────────────────────────────────────\n | \"user.profile:read\"\n | \"user:read\"\n | \"user:write\"\n | \"user.tfa:write\"\n | \"user.assignments:read\"\n | \"user.assignments:write\"\n | \"user.notifications:read\"\n | \"user.notifications:write\"\n\n // ── Organization ────────────────────────────────────────────────────\n | \"organizations:read\"\n | \"organization:read\"\n | \"organization.roles:read\"\n | \"organization.share:read\"\n | \"organization.share:write\"\n | \"organization.ownership:write\"\n | \"organization.settings:write\"\n | \"organization.logs:read\"\n | \"organization.usage:read\"\n | \"organization.jobs:read\"\n | \"organization.jobs:write\"\n\n // ── Stack management ────────────────────────────────────────────────\n | \"cm.stacks.management:read\"\n | \"cm.stacks.management:write\"\n | \"cm.stack.management:read\"\n | \"cm.stack.management:write\"\n | \"cm.stack.settings:read\"\n | \"cm.stack.settings:write\"\n | \"cm.stack:share\"\n | \"cm.stack:unshare\"\n | \"cm.stack.users:read\"\n | \"cm.stack.users:write\"\n\n // ── Tokens ──────────────────────────────────────────────────────────\n | \"cm.stack.delivery-tokens:read\"\n | \"cm.stack.delivery-tokens:write\"\n | \"cm.stack.management-tokens:read\"\n | \"cm.stack.management-tokens:write\"\n\n // ── Content types ───────────────────────────────────────────────────\n | \"cm.content-types.management:read\"\n | \"cm.content-types.management:write\"\n | \"cm.content-types:import\"\n | \"cm.content-types:export\"\n | \"cm.content-type:read\"\n | \"cm.content-type:write\"\n | \"cm.content-type:copy\"\n\n // ── Global fields ───────────────────────────────────────────────────\n | \"cm.global-fields.management:read\"\n | \"cm.global-fields.management:write\"\n | \"cm.global-fields:import\"\n | \"cm.global-fields:export\"\n\n // ── Entries ──────────────────────────────────────────────────────────\n | \"cm.entries.management:read\"\n | \"cm.entries.management:write\"\n | \"cm.entries:import\"\n | \"cm.entries:export\"\n | \"cm.entry:read\"\n | \"cm.entry:write\"\n | \"cm.entry:publish\"\n | \"cm.entry:unpublish\"\n | \"cm.entry.workflow:write\"\n\n // ── Webhooks ────────────────────────────────────────────────────────\n | \"cm.webhooks.management:read\"\n | \"cm.webhooks.management:write\"\n | \"cm.webhooks:import\"\n | \"cm.webhooks:export\"\n | \"cm.webhook:read\"\n | \"cm.webhook:write\"\n\n // ── Assets ──────────────────────────────────────────────────────────\n | \"cm.assets.management:read\"\n | \"cm.assets.management:write\"\n | \"cm.assets.rt:read\"\n | \"cm.assets.rt:write\"\n | \"cm.assets:download\"\n | \"cm.asset:read\"\n | \"cm.asset:write\"\n | \"cm.asset:publish\"\n | \"cm.asset:unpublish\"\n\n // ── Workflows ───────────────────────────────────────────────────────\n | \"cm.workflows.management:read\"\n | \"cm.workflows.management:write\"\n | \"cm.workflows.publishing-rules:read\"\n | \"cm.workflows.publishing-rules:write\"\n\n // ── Environments ────────────────────────────────────────────────────\n | \"cm.environments.management:read\"\n | \"cm.environments.management:write\"\n\n // ── Extensions ──────────────────────────────────────────────────────\n | \"cm.extensions.management:read\"\n | \"cm.extensions.management:write\"\n\n // ── Languages ───────────────────────────────────────────────────────\n | \"cm.languages.management:read\"\n | \"cm.languages.management:write\"\n\n // ── Labels ──────────────────────────────────────────────────────────\n | \"cm.labels.management:read\"\n | \"cm.labels.management:write\"\n\n // ── Bulk operations ─────────────────────────────────────────────────\n | \"cm.bulk-operations:publish\"\n | \"cm.bulk-operations:unpublish\"\n | \"cm.bulk-operations:add-to-release\"\n | \"cm.bulk-operations:delete\"\n | \"cm.bulk-operations:move-to-folder\"\n | \"cm.bulk-operations:workflow\"\n\n // ── Releases ────────────────────────────────────────────────────────\n | \"cm.releases.management:read\"\n | \"cm.releases.management:write\"\n | \"cm.release:read\"\n | \"cm.release:write\"\n | \"cm.release:clone\"\n | \"cm.release:deploy\"\n\n // ── Roles ───────────────────────────────────────────────────────────\n | \"cm.roles.management:read\"\n | \"cm.roles.management:write\"\n\n // ── Audit & publish queue ───────────────────────────────────────────\n | \"cm.audit-logs:read\"\n | \"cm.publish-queue.management:read\"\n | \"cm.publish-queue.management:write\"\n\n // ── Personalization ─────────────────────────────────────────────────\n | \"personalize:read\"\n | \"personalize:manage\"\n\n // ── Taxonomies ──────────────────────────────────────────────────────\n | \"cm.taxonomies.management:read\"\n | \"cm.taxonomies.management:write\"\n | \"cm.taxonomy.terms:read\"\n | \"cm.taxonomy.terms:write\"\n\n // ── Branches ────────────────────────────────────────────────────────\n | \"cm.branches.management:read\"\n | \"cm.branches.management:write\"\n | \"cm.branches:compare-merge\"\n | \"cm.branch-aliases.management:read\"\n | \"cm.branch-aliases.management:write\"\n\n // ── Launch ──────────────────────────────────────────────────────────\n | \"launch:manage\"\n | \"launch.projects:read\"\n | \"launch.projects:write\"\n | \"launch.projects:delete\"\n | \"launch.gitproviders:manage\"\n\n // ── Automation Hub ──────────────────────────────────────────────────\n | \"automationhub.projects.management:read\"\n | \"automationhub.projects.management:write\"\n | \"automationhub.automations:read\"\n | \"automationhub.automations:write\"\n | \"automationhub.executions:read\"\n | \"automationhub.audit-logs:read\"\n | \"automationhub.variables:read\"\n | \"automationhub.variables:write\"\n | \"automationhub.accounts:read\"\n\n // ── Brand Kit ───────────────────────────────────────────────────────\n | \"brand-kits:read\"\n | \"brand-kits:manage\"\n\n // ── Variants ────────────────────────────────────────────────────────\n | \"cm.variant:read\"\n | \"cm.variant:write\"\n\n // ── Analytics & Audit ───────────────────────────────────────────────\n | \"analytics:read\"\n | \"auditlogs:read\"\n\n // ── Teams ───────────────────────────────────────────────────────────\n | \"teams:read\"\n | \"teams:write\"\n\n/**\n * Human-readable descriptions for every Contentstack OAuth scope.\n *\n * Sourced from the Developer Hub API (`/manifests/oauth/scopes` endpoint).\n *\n * @example\n * ```ts\n * import { OAUTH_SCOPE_DESCRIPTIONS } from \"@timbenniks/contentstack-platform-sdk/auth\"\n *\n * // Get description for a scope\n * console.log(OAUTH_SCOPE_DESCRIPTIONS[\"cm.entries.management:read\"])\n * // → \"View all entries\"\n * ```\n */\nexport const OAUTH_SCOPE_DESCRIPTIONS: Record = {\n // Developer Hub (Apps)\n \"app.manifests:read\": \"View all manifests\",\n \"app.manifest:read\": \"View manifest details\",\n \"app.manifest:write\": \"Create, update, remove manifests\",\n \"app.hosting:read\": \"View hosting\",\n \"app.hosting:write\": \"Create, update, remove hosting\",\n \"app.installations:read\": \"View all installations\",\n \"app.installations.management:read\": \"View installation details\",\n \"app.installations.management:write\": \"Create, update, remove installations\",\n \"app.authorizations:manage\": \"Manage all authorizations\",\n \"app.authorizations.management:write\": \"Revoke all authorizations\",\n \"app.requests:write\": \"Create app request\",\n \"app.requests.management:write\": \"Revoke app request\",\n\n // SCIM\n \"scim:manage\": \"Manage users and groups using SCIM\",\n\n // User\n \"user.profile:read\": \"View user profile\",\n \"user:read\": \"View user details\",\n \"user:write\": \"Update user details\",\n \"user.tfa:write\": \"Verify, enable, disable and cancel user two-factor authentication\",\n \"user.assignments:read\": \"View user assignments\",\n \"user.assignments:write\": \"Update, remove user assignments\",\n \"user.notifications:read\": \"View user notifications\",\n \"user.notifications:write\": \"Update, remove user notifications\",\n\n // Organization\n \"organizations:read\": \"View details of organizations associated with the user\",\n \"organization:read\": \"View details of an organization\",\n \"organization.roles:read\": \"View organization level roles\",\n \"organization.share:read\": \"View details of organization invitations shared with users\",\n \"organization.share:write\": \"Update, remove organization invitation shares\",\n \"organization.ownership:write\": \"Create, update of organization ownership transfer\",\n \"organization.settings:write\": \"Update organization settings\",\n \"organization.logs:read\": \"View organization logs\",\n \"organization.usage:read\": \"View organization usage details\",\n \"organization.jobs:read\": \"View organization job details\",\n \"organization.jobs:write\": \"Remove, retry organization jobs\",\n\n // Stack management\n \"cm.stacks.management:read\": \"View all stacks\",\n \"cm.stacks.management:write\": \"Create, update, remove stacks\",\n \"cm.stack.management:read\": \"View a single stack details\",\n \"cm.stack.management:write\": \"Update stack management properties\",\n \"cm.stack.settings:read\": \"View stack settings details\",\n \"cm.stack.settings:write\": \"Update stack settings\",\n \"cm.stack:share\": \"Share stack invitation with users\",\n \"cm.stack:unshare\": \"Unshare stack invitations\",\n \"cm.stack.users:read\": \"View users associated with a stack\",\n \"cm.stack.users:write\": \"Update user roles and user associations with a stack\",\n\n // Tokens\n \"cm.stack.delivery-tokens:read\": \"View delivery tokens associated with a stack\",\n \"cm.stack.delivery-tokens:write\": \"Create, update, remove delivery tokens in a stack\",\n \"cm.stack.management-tokens:read\": \"View management tokens associated with a stack\",\n \"cm.stack.management-tokens:write\": \"Create, update, remove management tokens in a stack\",\n\n // Content types\n \"cm.content-types.management:read\": \"View all content types\",\n \"cm.content-types.management:write\": \"Create, update, remove content types\",\n \"cm.content-types:import\": \"Import content types\",\n \"cm.content-types:export\": \"Export content types\",\n \"cm.content-type:read\": \"View content type details\",\n \"cm.content-type:write\": \"Update content type details\",\n \"cm.content-type:copy\": \"Copy a content type\",\n\n // Global fields\n \"cm.global-fields.management:read\": \"View all global fields\",\n \"cm.global-fields.management:write\": \"Create, update, remove global fields\",\n \"cm.global-fields:import\": \"Import global fields\",\n \"cm.global-fields:export\": \"Export global fields\",\n\n // Entries\n \"cm.entries.management:read\": \"View all entries\",\n \"cm.entries.management:write\": \"Create, update, remove entries\",\n \"cm.entries:import\": \"Import entries\",\n \"cm.entries:export\": \"Export entries\",\n \"cm.entry:read\": \"View details associated with an entry\",\n \"cm.entry:write\": \"Update details associated with an entry\",\n \"cm.entry:publish\": \"Publish an entry\",\n \"cm.entry:unpublish\": \"Unpublish an entry\",\n \"cm.entry.workflow:write\": \"Create a workflow for an entry\",\n\n // Webhooks\n \"cm.webhooks.management:read\": \"View all webhooks\",\n \"cm.webhooks.management:write\": \"Create, update, remove webhooks\",\n \"cm.webhooks:import\": \"Import webhooks\",\n \"cm.webhooks:export\": \"Export webhooks\",\n \"cm.webhook:read\": \"View webhook details\",\n \"cm.webhook:write\": \"Update webhook details\",\n\n // Assets\n \"cm.assets.management:read\": \"View all assets\",\n \"cm.assets.management:write\": \"Create, update, remove assets\",\n \"cm.assets.rt:read\": \"View all RTE assets\",\n \"cm.assets.rt:write\": \"Create, update, remove RTE assets\",\n \"cm.assets:download\": \"Download assets\",\n \"cm.asset:read\": \"View asset details\",\n \"cm.asset:write\": \"Update asset details\",\n \"cm.asset:publish\": \"Publish an asset\",\n \"cm.asset:unpublish\": \"Unpublish an asset\",\n\n // Workflows\n \"cm.workflows.management:read\": \"View all workflows\",\n \"cm.workflows.management:write\": \"Create, update, remove workflows\",\n \"cm.workflows.publishing-rules:read\": \"View all workflow publishing rules\",\n \"cm.workflows.publishing-rules:write\": \"Create, update, remove workflow publishing rules\",\n\n // Environments\n \"cm.environments.management:read\": \"View all environments\",\n \"cm.environments.management:write\": \"Create, update, remove environments\",\n\n // Extensions\n \"cm.extensions.management:read\": \"View all extensions\",\n \"cm.extensions.management:write\": \"Create, update, remove extensions\",\n\n // Languages\n \"cm.languages.management:read\": \"View all languages\",\n \"cm.languages.management:write\": \"Create, update, remove languages\",\n\n // Labels\n \"cm.labels.management:read\": \"View all labels\",\n \"cm.labels.management:write\": \"Create, update, remove labels\",\n\n // Bulk operations\n \"cm.bulk-operations:publish\": \"Publish bulk operations\",\n \"cm.bulk-operations:unpublish\": \"Unpublish bulk operations\",\n \"cm.bulk-operations:add-to-release\": \"Add to release bulk operations\",\n \"cm.bulk-operations:delete\": \"Delete bulk operations\",\n \"cm.bulk-operations:move-to-folder\": \"Move to folder bulk operations\",\n \"cm.bulk-operations:workflow\": \"Workflow bulk operations\",\n\n // Releases\n \"cm.releases.management:read\": \"View all releases\",\n \"cm.releases.management:write\": \"Create, update, remove releases\",\n \"cm.release:read\": \"View details associated with a release\",\n \"cm.release:write\": \"Update details associated with a release\",\n \"cm.release:clone\": \"Clone a release\",\n \"cm.release:deploy\": \"Deploy a release\",\n\n // Roles\n \"cm.roles.management:read\": \"View all roles\",\n \"cm.roles.management:write\": \"Create, update, remove roles\",\n\n // Audit & publish queue\n \"cm.audit-logs:read\": \"View all audit logs\",\n \"cm.publish-queue.management:read\": \"View all publish queues\",\n \"cm.publish-queue.management:write\": \"Create, update, remove publish queues\",\n\n // Personalization\n \"personalize:read\": \"View all resources in a project\",\n \"personalize:manage\": \"Create, update and delete resources in a project\",\n\n // Taxonomies\n \"cm.taxonomies.management:read\": \"View all taxonomies\",\n \"cm.taxonomies.management:write\": \"Create, update, delete taxonomies\",\n \"cm.taxonomy.terms:read\": \"View all terms of a taxonomy\",\n \"cm.taxonomy.terms:write\": \"Create, update, move, delete term(s) of a taxonomy\",\n\n // Branches\n \"cm.branches.management:read\": \"View all branches\",\n \"cm.branches.management:write\": \"Create, delete branches\",\n \"cm.branches:compare-merge\": \"Compare, merge branches\",\n \"cm.branch-aliases.management:read\": \"View all branch aliases\",\n \"cm.branch-aliases.management:write\": \"Assign, delete branch aliases\",\n\n // Launch\n \"launch:manage\": \"Manage Contentstack Launch projects\",\n \"launch.projects:read\": \"View all projects\",\n \"launch.projects:write\": \"Create and update projects\",\n \"launch.projects:delete\": \"Delete projects\",\n \"launch.gitproviders:manage\": \"Manage External Git providers in Launch\",\n\n // Automation Hub\n \"automationhub.projects.management:read\": \"View all organization projects\",\n \"automationhub.projects.management:write\": \"Create, update and remove projects\",\n \"automationhub.automations:read\": \"View all automations in a project\",\n \"automationhub.automations:write\": \"Update automation settings\",\n \"automationhub.executions:read\": \"View all execution logs\",\n \"automationhub.audit-logs:read\": \"View all audit logs\",\n \"automationhub.variables:read\": \"View all project variables\",\n \"automationhub.variables:write\": \"Create, update, remove variables\",\n \"automationhub.accounts:read\": \"View all connected apps\",\n\n // Brand Kit\n \"brand-kits:read\": \"View all brand kits\",\n \"brand-kits:manage\": \"Create, read, update, and delete brand kits\",\n\n // Variants\n \"cm.variant:read\": \"View all variant groups and its variants\",\n \"cm.variant:write\": \"Create, update and remove variant groups and its variants\",\n\n // Analytics & Audit\n \"analytics:read\": \"View organization analytics\",\n \"auditlogs:read\": \"View organization auditlog\",\n\n // Teams\n \"teams:read\": \"View all teams\",\n \"teams:write\": \"Create, update and delete teams\",\n} as const\n\n/**\n * Pre-built scope combinations for common use cases.\n *\n * Each preset includes `user:read` as a baseline since it is required\n * for all OAuth flows that need user profile information.\n *\n * @example\n * ```ts\n * import { OAUTH_SCOPE_PRESETS } from \"@timbenniks/contentstack-platform-sdk/auth\"\n *\n * const config: OAuthConfig = {\n * scopes: OAUTH_SCOPE_PRESETS.cmsAuthoring,\n * // ...\n * }\n * ```\n */\nexport const OAUTH_SCOPE_PRESETS = {\n /** Minimal: only read the authenticated user's profile. */\n readOnly: [\"user:read\"] as const,\n\n /** Read content types, entries, and assets. */\n contentReader: [\n \"user:read\",\n \"cm.content-types.management:read\",\n \"cm.entries.management:read\",\n \"cm.assets.management:read\",\n ] as const,\n\n /** Read and write entries and assets; read content types. */\n cmsAuthoring: [\n \"user:read\",\n \"cm.content-types.management:read\",\n \"cm.entries.management:read\",\n \"cm.entries.management:write\",\n \"cm.entry:publish\",\n \"cm.entry:unpublish\",\n \"cm.assets.management:read\",\n \"cm.assets.management:write\",\n \"cm.asset:publish\",\n \"cm.asset:unpublish\",\n ] as const,\n\n /** CMS authoring plus taxonomy management. */\n cmsAuthoringWithTaxonomies: [\n \"user:read\",\n \"cm.content-types.management:read\",\n \"cm.entries.management:read\",\n \"cm.entries.management:write\",\n \"cm.entry:publish\",\n \"cm.entry:unpublish\",\n \"cm.assets.management:read\",\n \"cm.assets.management:write\",\n \"cm.asset:publish\",\n \"cm.asset:unpublish\",\n \"cm.taxonomies.management:read\",\n \"cm.taxonomies.management:write\",\n \"cm.taxonomy.terms:read\",\n \"cm.taxonomy.terms:write\",\n ] as const,\n\n /** Brand Kit: read and manage voice profiles and knowledge vault. */\n brandKit: [\"user:read\", \"brand-kits:read\", \"brand-kits:manage\"] as const,\n\n /** Launch: manage projects and deployments. */\n launch: [\n \"user:read\",\n \"launch:manage\",\n \"launch.projects:read\",\n \"launch.projects:write\",\n \"launch.projects:delete\",\n ] as const,\n\n /** Personalization: read and manage experiences. */\n personalization: [\"user:read\", \"personalize:read\", \"personalize:manage\"] as const,\n\n /** Developer Hub: read and manage apps, installations, authorizations, and hosting. */\n developerHub: [\n \"user:read\",\n \"app.manifests:read\",\n \"app.manifest:read\",\n \"app.manifest:write\",\n \"app.hosting:read\",\n \"app.hosting:write\",\n \"app.installations:read\",\n \"app.installations.management:read\",\n \"app.installations.management:write\",\n \"app.authorizations:manage\",\n \"app.authorizations.management:write\",\n \"app.requests:write\",\n \"app.requests.management:write\",\n ] as const,\n\n /** Automation Hub: manage automations and variables. */\n automationHub: [\n \"user:read\",\n \"automationhub.projects.management:read\",\n \"automationhub.projects.management:write\",\n \"automationhub.automations:read\",\n \"automationhub.automations:write\",\n \"automationhub.executions:read\",\n \"automationhub.variables:read\",\n \"automationhub.variables:write\",\n \"automationhub.accounts:read\",\n ] as const,\n} satisfies Record\n","import {\n ContentstackAuthError,\n ContentstackConfigError,\n ContentstackError,\n ContentstackForbiddenError,\n ContentstackInvalidApiKeyError,\n ContentstackNotFoundError,\n ContentstackRateLimitError,\n ContentstackServerError,\n ContentstackValidationError,\n} from \"./errors.js\"\nimport type { HttpClientConfig, HttpResponse } from \"./types.js\"\n\nconst DEFAULT_TIMEOUT = 30_000\nconst DEFAULT_RETRY_LIMIT = 5\nconst DEFAULT_RETRY_DELAY = 300\nconst MAX_JITTER = 100\n\nexport class ContentstackHttpClient {\n private readonly config: Required<\n Pick\n > & {\n headers: Record\n fetch: typeof globalThis.fetch\n resolveHeaders?: HttpClientConfig[\"resolveHeaders\"]\n }\n\n constructor(config: HttpClientConfig) {\n this.config = {\n baseUrl: config.baseUrl,\n headers: config.headers ?? {},\n timeout: config.timeout ?? DEFAULT_TIMEOUT,\n retryOnError: config.retryOnError ?? true,\n retryLimit: config.retryLimit ?? DEFAULT_RETRY_LIMIT,\n retryDelay: config.retryDelay ?? DEFAULT_RETRY_DELAY,\n fetch: config.fetch ?? globalThis.fetch.bind(globalThis),\n resolveHeaders: config.resolveHeaders,\n }\n }\n\n async get(path: string, params?: Record): Promise> {\n let url = `${this.config.baseUrl}${path}`\n if (params) {\n const searchParams = new URLSearchParams(params)\n url += `?${searchParams.toString()}`\n }\n return this.request(url, { method: \"GET\" }, path)\n }\n\n async post(path: string, body?: unknown): Promise> {\n const url = `${this.config.baseUrl}${path}`\n return this.request(\n url,\n {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\" },\n body: body !== undefined ? JSON.stringify(body) : undefined,\n },\n path,\n )\n }\n\n async put(path: string, body?: unknown): Promise> {\n const url = `${this.config.baseUrl}${path}`\n return this.request(\n url,\n {\n method: \"PUT\",\n headers: { \"Content-Type\": \"application/json\" },\n body: body !== undefined ? JSON.stringify(body) : undefined,\n },\n path,\n )\n }\n\n async patch(path: string, body?: unknown): Promise> {\n const url = `${this.config.baseUrl}${path}`\n return this.request(\n url,\n {\n method: \"PATCH\",\n headers: { \"Content-Type\": \"application/json\" },\n body: body !== undefined ? JSON.stringify(body) : undefined,\n },\n path,\n )\n }\n\n async delete(path: string): Promise> {\n const url = `${this.config.baseUrl}${path}`\n return this.request(url, { method: \"DELETE\" }, path)\n }\n\n async postForm(path: string, params: URLSearchParams): Promise> {\n const url = `${this.config.baseUrl}${path}`\n return this.request(\n url,\n {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/x-www-form-urlencoded\" },\n body: params.toString(),\n },\n path,\n )\n }\n\n async upload(path: string, form: FormData): Promise> {\n const url = `${this.config.baseUrl}${path}`\n return this.request(url, { method: \"POST\", body: form }, path)\n }\n\n /** Return a new client with additional headers merged */\n withHeaders(headers: Record): ContentstackHttpClient {\n return new ContentstackHttpClient({\n ...this.config,\n headers: { ...this.config.headers, ...headers },\n })\n }\n\n /** Return a new client with a different base URL */\n withBaseUrl(baseUrl: string): ContentstackHttpClient {\n return new ContentstackHttpClient({\n ...this.config,\n baseUrl,\n })\n }\n\n private async request(url: string, init: RequestInit, path: string): Promise> {\n const headers = new Headers(this.config.headers)\n const resolvedHeaders = await this.config.resolveHeaders?.()\n\n if (resolvedHeaders) {\n for (const [key, value] of Object.entries(resolvedHeaders)) {\n headers.set(key, value)\n }\n }\n\n if (init.headers) {\n const initHeaders =\n init.headers instanceof Headers\n ? init.headers\n : new Headers(init.headers as Record)\n initHeaders.forEach((value, key) => headers.set(key, value))\n }\n\n let lastError: Error | undefined\n const maxAttempts = this.config.retryOnError ? this.config.retryLimit + 1 : 1\n\n for (let attempt = 0; attempt < maxAttempts; attempt++) {\n const controller = new AbortController()\n const timeoutId = setTimeout(() => controller.abort(), this.config.timeout)\n\n try {\n const response = await this.config.fetch(url, {\n ...init,\n headers,\n signal: controller.signal,\n })\n\n if (response.ok) {\n const data = (await response.json().catch(() => ({}))) as T\n return { data, status: response.status, headers: response.headers }\n }\n\n // Check if retryable\n const isRetryable = response.status === 429 || response.status >= 500\n if (isRetryable && this.config.retryOnError && attempt < maxAttempts - 1) {\n const delay = this.calculateDelay(response, attempt)\n await sleep(delay)\n lastError = await this.createError(response, path)\n continue\n }\n\n throw await this.createError(response, path)\n } catch (error) {\n if (error instanceof ContentstackError) {\n throw error\n }\n\n if (error instanceof ContentstackConfigError) {\n throw error\n }\n\n if (error instanceof DOMException && error.name === \"AbortError\") {\n throw new ContentstackError(`Request timed out after ${this.config.timeout}ms`, {\n requestPath: path,\n cause: error,\n })\n }\n\n throw new ContentstackError(\"Network request failed\", {\n requestPath: path,\n cause: error instanceof Error ? error : new Error(String(error)),\n })\n } finally {\n clearTimeout(timeoutId)\n }\n }\n\n // Should not reach here, but just in case\n throw lastError ?? new ContentstackError(\"Request failed after retries\", { requestPath: path })\n }\n\n private calculateDelay(response: Response, attempt: number): number {\n const retryAfter = response.headers.get(\"Retry-After\")\n if (retryAfter) {\n const seconds = Number.parseFloat(retryAfter)\n if (!Number.isNaN(seconds)) {\n return seconds * 1000\n }\n }\n\n const jitter = Math.random() * MAX_JITTER\n return this.config.retryDelay * 2 ** attempt + jitter\n }\n\n private async createError(response: Response, path: string): Promise {\n let body: Record = {}\n try {\n body = (await response.json()) as Record\n } catch {\n // Response body may not be JSON\n }\n\n const message =\n (body.error_message as string | undefined) ??\n (body.error_description as string | undefined) ??\n (body.message as string | undefined) ??\n `HTTP ${response.status} error`\n const errorCode = body.error_code as number | undefined\n const errors = body.errors as Record | undefined\n const retryAfter = response.headers.get(\"Retry-After\")\n\n const opts = { status: response.status, errorCode, errors, requestPath: path }\n\n switch (response.status) {\n case 400:\n return new ContentstackValidationError(message, { ...opts, status: 400 })\n case 401:\n return new ContentstackAuthError(message, opts)\n case 403:\n return new ContentstackForbiddenError(message, opts)\n case 404:\n return new ContentstackNotFoundError(message, opts)\n case 412:\n return new ContentstackInvalidApiKeyError(message, opts)\n case 422:\n return new ContentstackValidationError(message, { ...opts, status: 422 })\n case 429:\n return new ContentstackRateLimitError(message, {\n ...opts,\n retryAfter: retryAfter ? Number.parseFloat(retryAfter) : undefined,\n })\n default:\n if (response.status >= 500) {\n return new ContentstackServerError(message, opts)\n }\n return new ContentstackError(message, opts)\n }\n }\n}\n\nfunction sleep(ms: number): Promise {\n return new Promise((resolve) => setTimeout(resolve, ms))\n}\n","const CHARSET = \"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~\"\n\n/**\n * Generate a cryptographically random code verifier for PKCE.\n * Returns a 43-character URL-safe string (the minimum length per RFC 7636).\n * Uses globalThis.crypto for cross-runtime compatibility (Node 18+, Deno, Bun, edge).\n */\nexport function generateCodeVerifier(): string {\n const bytes = new Uint8Array(43)\n globalThis.crypto.getRandomValues(bytes)\n let result = \"\"\n for (const byte of bytes) {\n result += CHARSET[byte % CHARSET.length]\n }\n return result\n}\n\n/**\n * Compute an S256 code challenge from a code verifier.\n * SHA-256 hash → base64url encoded (no padding).\n * Uses globalThis.crypto.subtle for cross-runtime compatibility.\n */\nexport async function generateCodeChallenge(verifier: string): Promise {\n const encoder = new TextEncoder()\n const data = encoder.encode(verifier)\n const digest = await globalThis.crypto.subtle.digest(\"SHA-256\", data)\n const bytes = new Uint8Array(digest)\n let binary = \"\"\n for (const byte of bytes) {\n binary += String.fromCharCode(byte)\n }\n return btoa(binary).replace(/\\+/g, \"-\").replace(/\\//g, \"_\").replace(/=+$/, \"\")\n}\n","import { ContentstackHttpClient } from \"../http/client.js\"\nimport {\n ContentstackAuthError,\n ContentstackConfigError,\n ContentstackError,\n} from \"../http/errors.js\"\nimport type { ContentstackRegion } from \"../regions/index.js\"\nimport { resolveEndpoints } from \"../regions/index.js\"\nimport { generateCodeChallenge, generateCodeVerifier } from \"./pkce.js\"\nimport type { AuthHttpOptions, ContentstackUser, OAuthConfig, OAuthTokens } from \"./types.js\"\n\ninterface AuthorizationUrlOptions {\n state?: string\n usePKCE?: boolean\n}\n\ninterface AuthorizationUrlResult {\n url: string\n state: string\n codeVerifier?: string\n}\n\ninterface ExchangeCodeOptions {\n codeVerifier?: string\n httpOptions?: AuthHttpOptions\n}\n\nfunction validateConfig(config: OAuthConfig): void {\n if (!config.appId) {\n throw new ContentstackConfigError(\n \"appId is required for OAuth. This is your Contentstack app's UID, not the client ID.\",\n )\n }\n if (config.appId === config.clientId) {\n throw new ContentstackConfigError(\n \"appId and clientId must be different. appId is your Contentstack app UID; clientId is the OAuth client identifier.\",\n )\n }\n}\n\n/**\n * Build a Contentstack OAuth authorization URL.\n *\n * @example\n * ```ts\n * const { url, state, codeVerifier } = await buildAuthorizationUrl({\n * region: \"us\",\n * appId: \"app-uid\",\n * clientId: \"client-id\",\n * clientSecret: \"secret\",\n * scopes: [\"user:read\"],\n * redirectUri: \"http://localhost:3000/api/auth/callback/contentstack\",\n * }, { usePKCE: true })\n * ```\n */\nexport async function buildAuthorizationUrl(\n config: OAuthConfig,\n options?: AuthorizationUrlOptions,\n): Promise {\n validateConfig(config)\n\n const endpoints = resolveEndpoints(config.region)\n const authorizationUrl = `${endpoints.app}/apps/${config.appId}/authorize`\n\n const state = options?.state ?? generateCodeVerifier()\n\n const params = new URLSearchParams({\n response_type: \"code\",\n client_id: config.clientId,\n redirect_uri: config.redirectUri,\n scope: config.scopes.join(\" \"),\n state,\n })\n\n let codeVerifier: string | undefined\n if (options?.usePKCE) {\n codeVerifier = generateCodeVerifier()\n const codeChallenge = await generateCodeChallenge(codeVerifier)\n params.set(\"code_challenge\", codeChallenge)\n params.set(\"code_challenge_method\", \"S256\")\n }\n\n return {\n url: `${authorizationUrl}?${params.toString()}`,\n state,\n codeVerifier,\n }\n}\n\nfunction mapTokenResponse(data: Record): OAuthTokens {\n return {\n accessToken: data.access_token as string,\n refreshToken: (data.refresh_token as string | undefined) ?? \"\",\n expiresIn: data.expires_in as number,\n tokenType: data.token_type as string,\n }\n}\n\nasync function makeTokenRequest(\n appBaseUrl: string,\n body: URLSearchParams,\n errorMessage: string,\n httpOptions?: AuthHttpOptions,\n): Promise {\n const client = new ContentstackHttpClient({ ...httpOptions, baseUrl: appBaseUrl })\n try {\n const { data } = await client.postForm>(\"/apps-api/token\", body)\n return mapTokenResponse(data)\n } catch (err) {\n if (err instanceof ContentstackError) {\n throw new ContentstackAuthError(err.message || errorMessage, {\n status: err.status,\n requestPath: \"/apps-api/token\",\n cause: err,\n })\n }\n throw new ContentstackAuthError(errorMessage, {\n requestPath: \"/apps-api/token\",\n cause: err instanceof Error ? err : undefined,\n })\n }\n}\n\n/**\n * Exchange an authorization code for OAuth tokens.\n */\nexport async function exchangeCode(\n config: OAuthConfig,\n code: string,\n options?: ExchangeCodeOptions,\n): Promise {\n const endpoints = resolveEndpoints(config.region)\n\n const body = new URLSearchParams({\n grant_type: \"authorization_code\",\n code,\n redirect_uri: config.redirectUri,\n client_id: config.clientId,\n client_secret: config.clientSecret,\n })\n\n if (options?.codeVerifier) {\n body.set(\"code_verifier\", options.codeVerifier)\n }\n\n return makeTokenRequest(\n endpoints.app,\n body,\n \"Failed to exchange authorization code\",\n options?.httpOptions,\n )\n}\n\n/**\n * Refresh an expired access token using a refresh token.\n */\nexport async function refreshToken(\n config: OAuthConfig,\n token: string,\n options?: { httpOptions?: AuthHttpOptions },\n): Promise {\n const endpoints = resolveEndpoints(config.region)\n\n const body = new URLSearchParams({\n grant_type: \"refresh_token\",\n refresh_token: token,\n client_id: config.clientId,\n client_secret: config.clientSecret,\n })\n\n return makeTokenRequest(endpoints.app, body, \"Failed to refresh token\", options?.httpOptions)\n}\n\nexport interface AppTokenCredentials {\n clientId: string\n clientSecret: string\n}\n\n/**\n * Obtain an app token (client credentials grant) for machine-to-machine integrations.\n * Requires the app's `app_token_config` to be enabled with the needed scopes.\n */\nexport async function exchangeAppToken(\n region: ContentstackRegion,\n credentials: AppTokenCredentials,\n options?: { httpOptions?: AuthHttpOptions },\n): Promise {\n const endpoints = resolveEndpoints(region)\n\n const body = new URLSearchParams({\n grant_type: \"client_credentials\",\n client_id: credentials.clientId,\n client_secret: credentials.clientSecret,\n })\n\n return makeTokenRequest(endpoints.app, body, \"Failed to obtain app token\", options?.httpOptions)\n}\n\nfunction mapUser(user: Record): ContentstackUser {\n return {\n uid: user.uid as string,\n email: user.email as string,\n firstName: (user.first_name as string) ?? undefined,\n lastName: (user.last_name as string) ?? undefined,\n username: (user.username as string) ?? undefined,\n profileImage: (user.profile_image as string) ?? undefined,\n }\n}\n\n/**\n * Fetch the authenticated user's profile from Contentstack.\n * Unwraps the nested `user` key and maps snake_case → camelCase.\n */\nexport async function getUser(\n region: ContentstackRegion,\n accessToken: string,\n options?: { httpOptions?: AuthHttpOptions },\n): Promise {\n const endpoints = resolveEndpoints(region)\n const client = new ContentstackHttpClient({\n ...options?.httpOptions,\n baseUrl: `${endpoints.cma}/v3`,\n headers: { Authorization: `Bearer ${accessToken}` },\n })\n\n try {\n const { data } = await client.get<{ user: Record }>(\"/user\")\n return mapUser(data.user)\n } catch (err) {\n if (err instanceof ContentstackError) {\n throw new ContentstackAuthError(err.message || \"Failed to fetch user profile\", {\n status: err.status,\n requestPath: \"/v3/user\",\n cause: err,\n })\n }\n throw new ContentstackAuthError(\"Failed to fetch user profile\", {\n requestPath: \"/v3/user\",\n cause: err instanceof Error ? err : undefined,\n })\n }\n}\n\n/**\n * Create an Auth.js v5 provider config object for Contentstack.\n *\n * No Auth.js dependency is required in this package — the returned object\n * conforms to the Auth.js OAuthConfig shape and can be passed directly to\n * `next-auth` or `@auth/core`.\n *\n * @example\n * ```ts\n * // app/api/auth/[...nextauth]/route.ts\n * import NextAuth from \"next-auth\"\n * import { createAuthProvider } from \"@timbenniks/contentstack-platform-sdk/auth\"\n *\n * export const { handlers, signIn, signOut, auth } = NextAuth({\n * providers: [createAuthProvider({ region: \"us\", appId: \"...\", ... })],\n * })\n * ```\n */\nexport function createAuthProvider(config: OAuthConfig): Record {\n validateConfig(config)\n\n const endpoints = resolveEndpoints(config.region)\n const userClient = new ContentstackHttpClient({ baseUrl: `${endpoints.cma}/v3` })\n\n return {\n id: \"contentstack\",\n name: \"Contentstack\",\n type: \"oauth\",\n checks: [\"state\"],\n authorization: {\n url: `${endpoints.app}/apps/${config.appId}/authorize`,\n params: {\n response_type: \"code\",\n scope: config.scopes.join(\" \"),\n },\n },\n token: `${endpoints.app}/apps-api/token`,\n userinfo: {\n url: `${endpoints.cma}/v3/user`,\n async request({ tokens }: { tokens: { access_token: string } }) {\n const authedClient = userClient.withHeaders({\n Authorization: `Bearer ${tokens.access_token}`,\n })\n const { data } = await authedClient.get>(\"/user\")\n return data\n },\n },\n profile(profile: { user: Record }) {\n const user = profile.user\n return {\n id: user.uid as string,\n name:\n [user.first_name, user.last_name].filter(Boolean).join(\" \") || (user.username as string),\n email: user.email as string,\n image: (user.profile_image as string) ?? null,\n }\n },\n clientId: config.clientId,\n clientSecret: config.clientSecret,\n }\n}\n\n/**\n * Create Auth.js v5 callbacks for token persistence and automatic refresh.\n *\n * The `jwt` callback persists OAuth tokens on initial sign-in and attempts\n * to refresh expired tokens (with a 60-second safety window).\n *\n * The `session` callback exposes the access token and any refresh errors\n * on the session object.\n *\n * @example\n * ```ts\n * import NextAuth from \"next-auth\"\n * import { createAuthProvider, contentstackAuthCallbacks } from \"@timbenniks/contentstack-platform-sdk/auth\"\n *\n * export const { handlers, auth } = NextAuth({\n * providers: [createAuthProvider({ ... })],\n * callbacks: contentstackAuthCallbacks({ region: \"us\", ... }),\n * })\n * ```\n */\nexport function contentstackAuthCallbacks(config: OAuthConfig) {\n return {\n async jwt({\n token,\n account,\n }: { token: Record; account?: Record | null }) {\n // Initial sign-in: persist tokens from the OAuth account\n if (account) {\n token.accessToken = account.access_token\n token.refreshToken = account.refresh_token\n token.accessTokenExpiresAt = Date.now() + ((account.expires_in as number) ?? 3600) * 1000\n return token\n }\n\n // Subsequent calls: check if token needs refresh (60s safety window)\n const expiresAt = token.accessTokenExpiresAt as number | undefined\n if (expiresAt && Date.now() < expiresAt - 60_000) {\n return token\n }\n\n // Token is expired or about to expire — attempt refresh\n const currentRefreshToken = token.refreshToken as string | undefined\n if (!currentRefreshToken) {\n token.error = \"RefreshAccessTokenError\"\n return token\n }\n\n try {\n const tokens = await refreshToken(config, currentRefreshToken)\n token.accessToken = tokens.accessToken\n token.refreshToken = tokens.refreshToken\n token.accessTokenExpiresAt = Date.now() + tokens.expiresIn * 1000\n token.error = undefined\n } catch {\n token.error = \"RefreshAccessTokenError\"\n }\n\n return token\n },\n async session({\n session,\n token,\n }: { session: Record; token: Record }) {\n session.accessToken = token.accessToken\n if (token.error) {\n session.error = token.error\n }\n return session\n },\n }\n}\n","import { ContentstackHttpClient } from \"../http/client.js\"\nimport {\n ContentstackAuthError,\n ContentstackConfigError,\n ContentstackError,\n} from \"../http/errors.js\"\nimport type { ContentstackRegion } from \"../regions/index.js\"\nimport { resolveEndpoints } from \"../regions/index.js\"\nimport type {\n AuthHttpOptions,\n ContentstackCredentials,\n ContentstackCredentialsSession,\n ContentstackUser,\n} from \"./types.js\"\n\ntype SessionAuth = { type: \"oauth\"; accessToken: string } | { type: \"authtoken\"; token: string }\n\nfunction mapUser(user: Record): ContentstackUser {\n return {\n uid: user.uid as string,\n email: user.email as string,\n firstName: (user.first_name as string) ?? undefined,\n lastName: (user.last_name as string) ?? undefined,\n username: (user.username as string) ?? undefined,\n profileImage: (user.profile_image as string) ?? undefined,\n }\n}\n\nfunction createCMAHttpClient(\n region: ContentstackRegion,\n options?: AuthHttpOptions,\n headers?: Record,\n): ContentstackHttpClient {\n const endpoints = resolveEndpoints(region)\n\n return new ContentstackHttpClient({\n ...options,\n baseUrl: `${endpoints.cma}/v3`,\n headers,\n })\n}\n\nfunction resolveTfaToken(credentials: ContentstackCredentials): string | undefined {\n return credentials.otp ?? credentials.tfaToken\n}\n\nexport async function loginWithCredentials(\n region: ContentstackRegion,\n credentials: ContentstackCredentials,\n options?: { httpOptions?: AuthHttpOptions },\n): Promise {\n if (!credentials.email) {\n throw new ContentstackConfigError(\"email is required for credentials login\")\n }\n\n if (!credentials.password) {\n throw new ContentstackConfigError(\"password is required for credentials login\")\n }\n\n const client = createCMAHttpClient(region, options?.httpOptions)\n const tfaToken = resolveTfaToken(credentials)\n\n try {\n const { data } = await client.post<{\n notice?: string\n user?: Record & { authtoken?: string }\n }>(\"/user-session\", {\n user: {\n email: credentials.email,\n password: credentials.password,\n ...(tfaToken ? { tfa_token: tfaToken } : {}),\n },\n })\n\n const authtoken = data.user?.authtoken\n if (!data.user || !authtoken) {\n throw new ContentstackAuthError(\"Credentials login did not return an authtoken\", {\n requestPath: \"/user-session\",\n })\n }\n\n return {\n authtoken,\n user: mapUser(data.user),\n notice: data.notice,\n }\n } catch (error) {\n if (error instanceof ContentstackError) {\n throw error\n }\n\n throw new ContentstackAuthError(\"Failed to log in with Contentstack credentials\", {\n requestPath: \"/user-session\",\n cause: error instanceof Error ? error : undefined,\n })\n }\n}\n\nexport async function logoutUserSession(\n region: ContentstackRegion,\n authtoken: string,\n options?: { httpOptions?: AuthHttpOptions },\n): Promise {\n if (!authtoken) {\n throw new ContentstackConfigError(\"authtoken is required to log out a user session\")\n }\n\n const client = createCMAHttpClient(region, options?.httpOptions, { authtoken })\n await client.delete(\"/user-session\")\n}\n\nexport async function getCurrentUser(\n region: ContentstackRegion,\n auth: SessionAuth,\n options?: { httpOptions?: AuthHttpOptions },\n): Promise {\n const headers: Record = {}\n\n if (auth.type === \"oauth\") {\n headers.Authorization = `Bearer ${auth.accessToken}`\n } else {\n headers.authtoken = auth.token\n }\n\n const client = createCMAHttpClient(region, options?.httpOptions, headers)\n\n try {\n const { data } = await client.get<{ user: Record }>(\"/user\")\n return mapUser(data.user)\n } catch (error) {\n if (error instanceof ContentstackError) {\n throw new ContentstackAuthError(error.message || \"Failed to fetch user profile\", {\n status: error.status,\n requestPath: \"/user\",\n cause: error,\n })\n }\n\n throw new ContentstackAuthError(\"Failed to fetch user profile\", {\n requestPath: \"/user\",\n cause: error instanceof Error ? error : undefined,\n })\n }\n}\n","// @timbenniks/contentstack-platform-sdk — CMA pagination helper\n\nconst DEFAULT_PAGE_SIZE = 25\n\n/**\n * Create an AsyncIterable that lazily paginates through CMA results.\n * Pages are fetched on demand — only when items are consumed.\n */\nexport function paginate(\n fetchPage: (skip: number, limit: number) => Promise<{ items: T[]; count?: number }>,\n options?: { limit?: number },\n): AsyncIterable {\n const pageSize = options?.limit ?? DEFAULT_PAGE_SIZE\n\n return {\n [Symbol.asyncIterator]() {\n let skip = 0\n let done = false\n let buffer: T[] = []\n let bufferIndex = 0\n let totalCount: number | undefined\n\n return {\n async next(): Promise> {\n if (bufferIndex < buffer.length) {\n return { value: buffer[bufferIndex++] as T, done: false }\n }\n\n if (done) {\n return { value: undefined as unknown as T, done: true }\n }\n\n const page = await fetchPage(skip, pageSize)\n buffer = page.items\n bufferIndex = 0\n skip += page.items.length\n\n if (typeof page.count === \"number\") {\n totalCount = page.count\n }\n\n if (page.items.length === 0) {\n done = true\n return { value: undefined as unknown as T, done: true }\n }\n\n if (typeof totalCount === \"number\" && skip >= totalCount) {\n done = true\n }\n\n return { value: buffer[bufferIndex++] as T, done: false }\n },\n }\n },\n }\n}\n\n/**\n * Collect all items from an AsyncIterable into an array.\n * Replaces the repeated listAll() pattern across sub-clients.\n */\nexport async function collectAll(iterable: AsyncIterable): Promise {\n const items: T[] = []\n for await (const item of iterable) {\n items.push(item)\n }\n return items\n}\n","// @timbenniks/contentstack-platform-sdk — CMA AssetsClient\n\nimport type { ContentstackHttpClient } from \"../http/client.js\"\nimport { collectAll, paginate } from \"./pagination.js\"\nimport type { Asset, AssetFolder, BasePublishAction } from \"./types.js\"\n\nexport type AssetPublishAction = BasePublishAction\n\nexport class AssetsClient {\n constructor(private readonly http: ContentstackHttpClient) {}\n\n list(opts?: { limit?: number; folder?: string }): AsyncIterable {\n return paginate(\n async (skip, limit) => {\n const params: Record = {\n skip: String(skip),\n limit: String(limit),\n }\n if (opts?.folder) params.folder = opts.folder\n\n const response = await this.http.get<{ assets: Asset[]; count?: number }>(\"/assets\", params)\n return { items: response.data.assets ?? [], count: response.data.count }\n },\n { limit: opts?.limit },\n )\n }\n\n async listAll(opts?: { limit?: number; folder?: string }): Promise {\n return collectAll(this.list(opts))\n }\n\n async get(uid: string): Promise {\n const response = await this.http.get<{ asset: Asset }>(`/assets/${uid}`)\n return response.data.asset\n }\n\n async upload(form: FormData): Promise {\n const response = await this.http.upload<{ asset: Asset }>(\"/assets\", form)\n return response.data.asset\n }\n\n async update(uid: string, data: Partial): Promise {\n const response = await this.http.put<{ asset: Asset }>(`/assets/${uid}`, { asset: data })\n return response.data.asset\n }\n\n async delete(uid: string): Promise {\n await this.http.delete(`/assets/${uid}`)\n }\n\n async publish(uid: string, data: AssetPublishAction): Promise {\n await this.http.post(`/assets/${uid}/publish`, { asset: data })\n }\n\n async unpublish(uid: string, data: AssetPublishAction): Promise {\n await this.http.post(`/assets/${uid}/unpublish`, { asset: data })\n }\n\n // ─── Folders ──────────────────────────────────────────────────────\n\n async listFolders(opts?: { limit?: number }): Promise {\n const response = await this.http.get<{ assets: AssetFolder[] }>(\"/assets/folders\", {\n limit: String(opts?.limit ?? 100),\n })\n return response.data.assets ?? []\n }\n\n async getFolder(uid: string): Promise {\n const response = await this.http.get<{ asset: AssetFolder }>(`/assets/folders/${uid}`)\n return response.data.asset\n }\n\n async createFolder(data: { name: string; parent_uid?: string }): Promise {\n const response = await this.http.post<{ asset: AssetFolder }>(\"/assets/folders\", {\n asset: data,\n })\n return response.data.asset\n }\n\n async updateFolder(uid: string, data: { name: string }): Promise {\n const response = await this.http.put<{ asset: AssetFolder }>(`/assets/folders/${uid}`, {\n asset: data,\n })\n return response.data.asset\n }\n\n async deleteFolder(uid: string): Promise {\n await this.http.delete(`/assets/folders/${uid}`)\n }\n\n // ─── Additional Operations ──────────────────────────────────────\n\n async replace(uid: string, form: FormData): Promise {\n const response = await this.http.upload<{ asset: Asset }>(`/assets/${uid}`, form)\n return response.data.asset\n }\n\n async getReferences(uid: string): Promise {\n const response = await this.http.get<{ references: unknown[] }>(`/assets/${uid}/references`)\n return response.data.references ?? []\n }\n}\n","// @timbenniks/contentstack-platform-sdk — CMA base CRUD client\n\nimport type { ContentstackHttpClient } from \"../http/client.js\"\nimport { collectAll, paginate } from \"./pagination.js\"\n\nexport interface CrudConfig {\n basePath: string\n singularKey: string\n pluralKey: string\n}\n\nexport class CrudClient {\n constructor(\n protected readonly http: ContentstackHttpClient,\n protected readonly config: CrudConfig,\n ) {}\n\n list(opts?: { limit?: number }): AsyncIterable {\n return paginate(\n async (skip, limit) => {\n const response = await this.http.get>(this.config.basePath, {\n skip: String(skip),\n limit: String(limit),\n })\n const items = (response.data[this.config.pluralKey] as T[]) ?? []\n return { items, count: response.data.count as number | undefined }\n },\n { limit: opts?.limit },\n )\n }\n\n async listAll(opts?: { limit?: number }): Promise {\n return collectAll(this.list(opts))\n }\n\n async get(uid: string): Promise {\n const response = await this.http.get>(`${this.config.basePath}/${uid}`)\n return response.data[this.config.singularKey] as T\n }\n\n async create(data: Partial): Promise {\n const response = await this.http.post>(this.config.basePath, {\n [this.config.singularKey]: data,\n })\n return response.data[this.config.singularKey] as T\n }\n\n async update(uid: string, data: Partial): Promise {\n const response = await this.http.put>(\n `${this.config.basePath}/${uid}`,\n { [this.config.singularKey]: data },\n )\n return response.data[this.config.singularKey] as T\n }\n\n async delete(uid: string): Promise {\n await this.http.delete(`${this.config.basePath}/${uid}`)\n }\n}\n","// @timbenniks/contentstack-platform-sdk — CMA AuditLogClient\n\nimport type { ContentstackHttpClient } from \"../http/client.js\"\nimport { CrudClient } from \"./base-client.js\"\nimport type { AuditLogEntry } from \"./types.js\"\n\nexport class AuditLogClient extends CrudClient {\n constructor(http: ContentstackHttpClient) {\n super(http, { basePath: \"/audit-logs\", singularKey: \"audit_log\", pluralKey: \"audit_logs\" })\n }\n}\n","import { exchangeCode, loginWithCredentials, refreshToken } from \"../auth/index.js\"\nimport type {\n AuthHttpOptions,\n ContentstackCredentials,\n OAuthConfig,\n OAuthTokens,\n} from \"../auth/types.js\"\nimport { ContentstackConfigError } from \"../http/errors.js\"\nimport type { HttpHeadersResolver } from \"../http/types.js\"\nimport type { ContentstackRegion } from \"../regions/resolver.js\"\n\nconst DEFAULT_OAUTH_REFRESH_THRESHOLD_MS = 60_000\n\nexport interface CMAClientManagementTokenAuth {\n type: \"management-token\"\n token: string\n}\n\nexport interface CMAClientOAuthAuth {\n type: \"oauth\"\n accessToken?: string\n getAccessToken?: () => string | Promise\n}\n\nexport interface CMAClientAuthtokenAuth {\n type: \"authtoken\"\n token: string\n}\n\nexport interface CMAClientCredentialsAuth extends ContentstackCredentials {\n type: \"credentials\"\n}\n\nexport interface CMAClientOAuthFlowAuth {\n type: \"oauth-flow\"\n config: OAuthConfig\n tokens?: OAuthTokens\n code?: string\n codeVerifier?: string\n obtainedAt?: number\n refreshThresholdMs?: number\n onTokens?: (tokens: OAuthTokens & { obtainedAt: number }) => void | Promise\n}\n\nexport type CMAClientAuth =\n | CMAClientManagementTokenAuth\n | CMAClientOAuthAuth\n | CMAClientAuthtokenAuth\n | CMAClientCredentialsAuth\n | CMAClientOAuthFlowAuth\n\ninterface StoredOAuthTokens extends OAuthTokens {\n obtainedAt: number\n}\n\nfunction getStoredTokens(auth: CMAClientOAuthFlowAuth): StoredOAuthTokens | undefined {\n if (!auth.tokens) {\n return undefined\n }\n\n return {\n ...auth.tokens,\n obtainedAt: auth.obtainedAt ?? Date.now(),\n }\n}\n\nfunction isTokenExpired(tokens: StoredOAuthTokens, refreshThresholdMs: number): boolean {\n return Date.now() >= tokens.obtainedAt + tokens.expiresIn * 1000 - refreshThresholdMs\n}\n\nexport function createCMAAuthResolver(\n region: ContentstackRegion,\n auth: CMAClientAuth,\n httpOptions?: AuthHttpOptions,\n): HttpHeadersResolver {\n switch (auth.type) {\n case \"management-token\":\n return () => ({ authorization: auth.token })\n case \"authtoken\":\n return () => ({ authtoken: auth.token })\n case \"oauth\":\n return async () => {\n const accessToken = auth.accessToken ?? (await auth.getAccessToken?.())\n if (!accessToken) {\n throw new ContentstackConfigError(\"OAuth auth requires accessToken or getAccessToken()\")\n }\n\n return { authorization: `Bearer ${accessToken}` }\n }\n case \"credentials\": {\n let authtoken: string | undefined\n let loginPromise: Promise | undefined\n\n return async () => {\n if (authtoken) {\n return { authtoken }\n }\n\n if (!loginPromise) {\n loginPromise = loginWithCredentials(\n region,\n {\n email: auth.email,\n password: auth.password,\n otp: auth.otp,\n tfaToken: auth.tfaToken,\n },\n { httpOptions },\n )\n .then((session) => {\n authtoken = session.authtoken\n return authtoken\n })\n .finally(() => {\n loginPromise = undefined\n })\n }\n\n return { authtoken: await loginPromise }\n }\n }\n case \"oauth-flow\": {\n let currentTokens = getStoredTokens(auth)\n let tokenPromise: Promise | undefined\n const refreshThresholdMs = auth.refreshThresholdMs ?? DEFAULT_OAUTH_REFRESH_THRESHOLD_MS\n\n const persistTokens = async (tokens: OAuthTokens): Promise => {\n currentTokens = {\n ...tokens,\n obtainedAt: Date.now(),\n }\n await auth.onTokens?.(currentTokens)\n return currentTokens\n }\n\n const ensureTokens = async (): Promise => {\n if (currentTokens && !isTokenExpired(currentTokens, refreshThresholdMs)) {\n return currentTokens\n }\n\n if (!tokenPromise) {\n tokenPromise = (async () => {\n if (!currentTokens) {\n if (!auth.code) {\n throw new ContentstackConfigError(\n \"OAuth flow auth requires tokens or an authorization code\",\n )\n }\n\n return persistTokens(\n await exchangeCode(auth.config, auth.code, {\n codeVerifier: auth.codeVerifier,\n httpOptions,\n }),\n )\n }\n\n return persistTokens(\n await refreshToken(auth.config, currentTokens.refreshToken, {\n httpOptions,\n }),\n )\n })().finally(() => {\n tokenPromise = undefined\n })\n }\n\n return tokenPromise\n }\n\n return async () => {\n const tokens = await ensureTokens()\n return { authorization: `Bearer ${tokens.accessToken}` }\n }\n }\n }\n}\n","// @timbenniks/contentstack-platform-sdk — CMA BranchAliasesClient\n\nimport type { ContentstackHttpClient } from \"../http/client.js\"\nimport type { BranchAlias } from \"./types.js\"\n\nexport class BranchAliasesClient {\n constructor(private readonly http: ContentstackHttpClient) {}\n\n async list(): Promise {\n const response = await this.http.get<{ branch_aliases: BranchAlias[] }>(\n \"/stacks/branch_aliases\",\n )\n return response.data.branch_aliases ?? []\n }\n\n async get(uid: string): Promise {\n const response = await this.http.get<{ branch_alias: BranchAlias }>(\n `/stacks/branch_aliases/${uid}`,\n )\n return response.data.branch_alias\n }\n\n async createOrUpdate(uid: string, targetBranch: string): Promise {\n const response = await this.http.put<{ branch_alias: BranchAlias }>(\n `/stacks/branch_aliases/${uid}`,\n { branch_alias: { target_branch: targetBranch } },\n )\n return response.data.branch_alias\n }\n\n async delete(uid: string): Promise {\n await this.http.delete(`/stacks/branch_aliases/${uid}`)\n }\n}\n","// @timbenniks/contentstack-platform-sdk — CMA BranchesClient\n\nimport type { ContentstackHttpClient } from \"../http/client.js\"\nimport { collectAll, paginate } from \"./pagination.js\"\nimport type { Branch, MergeJob } from \"./types.js\"\n\nexport interface MergeRequest {\n base_branch: string\n compare_branch: string\n default_merge_strategy:\n | \"merge_prefer_base\"\n | \"merge_prefer_compare\"\n | \"overwrite_with_compare\"\n | \"merge_new_only\"\n | \"ignore\"\n merge_comment?: string\n item_merge_strategies?: Record\n}\n\nexport class BranchesClient {\n constructor(private readonly http: ContentstackHttpClient) {}\n\n list(opts?: { limit?: number }): AsyncIterable {\n return paginate(\n async (skip, limit) => {\n const response = await this.http.get<{ branches: Branch[]; count?: number }>(\n \"/stacks/branches\",\n { skip: String(skip), limit: String(limit) },\n )\n return { items: response.data.branches ?? [], count: response.data.count }\n },\n { limit: opts?.limit },\n )\n }\n\n async listAll(opts?: { limit?: number }): Promise {\n return collectAll(this.list(opts))\n }\n\n async get(uid: string): Promise {\n const response = await this.http.get<{ branch: Branch }>(`/stacks/branches/${uid}`)\n return response.data.branch\n }\n\n async create(data: { uid: string; source: string }): Promise {\n const response = await this.http.post<{ branch: Branch }>(\"/stacks/branches\", {\n branch: data,\n })\n return response.data.branch\n }\n\n async delete(uid: string): Promise {\n await this.http.delete(`/stacks/branches/${uid}`)\n }\n\n async compare(baseBranch: string, compareBranch: string): Promise {\n const response = await this.http.get(\"/stacks/branches_compare\", {\n base_branch: baseBranch,\n compare_branch: compareBranch,\n })\n return response.data\n }\n\n async merge(data: MergeRequest): Promise {\n const response = await this.http.post<{ merge_job: MergeJob }>(\"/stacks/branches_merge\", data)\n return response.data.merge_job\n }\n\n async listMergeJobs(): Promise {\n const response = await this.http.get<{ merge_jobs: MergeJob[] }>(\"/stacks/branches_queue\")\n return response.data.merge_jobs ?? []\n }\n\n async getMergeJob(uid: string): Promise {\n const response = await this.http.get<{ merge_job: MergeJob }>(`/stacks/branches_queue/${uid}`)\n return response.data.merge_job\n }\n}\n","// @timbenniks/contentstack-platform-sdk — CMA BulkOperationsClient\n\nimport type { ContentstackHttpClient } from \"../http/client.js\"\nimport type { BasePublishAction } from \"./types.js\"\n\nexport interface BulkEntry {\n uid: string\n content_type: string\n locale: string\n version?: number\n}\n\nexport interface BulkPublishAction extends BasePublishAction {\n entries?: BulkEntry[]\n assets?: Array<{ uid: string }>\n}\n\nexport interface BulkWorkflowAction {\n entries: Array<{\n uid: string\n content_type: string\n locale: string\n }>\n workflow_stage: {\n uid: string\n comment?: string\n }\n}\n\nexport class BulkOperationsClient {\n constructor(private readonly http: ContentstackHttpClient) {}\n\n async publish(data: BulkPublishAction): Promise {\n await this.http.post(\"/bulk/publish\", data)\n }\n\n async unpublish(data: BulkPublishAction): Promise {\n await this.http.post(\"/bulk/unpublish\", data)\n }\n\n async delete(data: {\n entries?: Array<{ uid: string; content_type: string; locale: string }>\n assets?: Array<{ uid: string }>\n }): Promise {\n await this.http.post(\"/bulk/delete\", data)\n }\n\n async updateWorkflow(data: BulkWorkflowAction): Promise {\n await this.http.post(\"/bulk/workflow\", data)\n }\n\n async addItems(data: Record): Promise {\n await this.http.post(\"/bulk/add\", data)\n }\n\n async updateItems(data: Record): Promise {\n await this.http.post(\"/bulk/update\", data)\n }\n\n async jobStatus(jobId: string): Promise {\n const response = await this.http.get<{ job: unknown }>(`/bulk/jobs/${jobId}`)\n return response.data.job\n }\n\n async getJobItems(jobId: string, opts?: { limit?: number; skip?: number }): Promise {\n const params: Record = {}\n if (opts?.limit) params.limit = String(opts.limit)\n if (opts?.skip) params.skip = String(opts.skip)\n const response = await this.http.get<{ items: unknown[] }>(\n `/bulk/jobs/${jobId}/items`,\n Object.keys(params).length > 0 ? params : undefined,\n )\n return response.data.items ?? []\n }\n}\n","// @timbenniks/contentstack-platform-sdk — CMA ContentTypesClient\n\nimport type { ContentstackHttpClient } from \"../http/client.js\"\nimport { CrudClient } from \"./base-client.js\"\nimport { collectAll, paginate } from \"./pagination.js\"\nimport type { ContentType } from \"./types.js\"\n\nexport class ContentTypesClient extends CrudClient {\n constructor(http: ContentstackHttpClient) {\n super(http, {\n basePath: \"/content_types\",\n singularKey: \"content_type\",\n pluralKey: \"content_types\",\n })\n }\n\n override list(opts?: { limit?: number; include_count?: boolean }): AsyncIterable {\n return paginate(\n async (skip, limit) => {\n const params: Record = {\n skip: String(skip),\n limit: String(limit),\n }\n if (opts?.include_count) params.include_count = \"true\"\n\n const response = await this.http.get<{\n content_types: ContentType[]\n count?: number\n }>(\"/content_types\", params)\n return { items: response.data.content_types ?? [], count: response.data.count }\n },\n { limit: opts?.limit },\n )\n }\n\n override async listAll(opts?: { limit?: number; include_count?: boolean }): Promise<\n ContentType[]\n > {\n return collectAll(this.list(opts))\n }\n\n async export(uid: string): Promise {\n const response = await this.http.get<{ content_type: ContentType }>(\n `/content_types/${uid}/export`,\n )\n return response.data.content_type\n }\n\n async import(data: Record): Promise {\n const response = await this.http.post<{ content_type: ContentType }>(\n \"/content_types/import\",\n data,\n )\n return response.data.content_type\n }\n}\n","// @timbenniks/contentstack-platform-sdk — CMA EntriesClient\n\nimport type { ContentstackHttpClient } from \"../http/client.js\"\nimport { collectAll, paginate } from \"./pagination.js\"\nimport type { BasePublishAction, Entry } from \"./types.js\"\n\nexport interface EntryListOptions {\n locale?: string\n include_publish_details?: boolean\n include_workflow?: boolean\n include_count?: boolean\n query?: Record\n asc?: string\n desc?: string\n limit?: number\n}\n\nexport interface EntryGetOptions {\n locale?: string\n include_publish_details?: boolean\n include_workflow?: boolean\n version?: number\n}\n\nexport type PublishAction = BasePublishAction\n\nexport interface WorkflowStageAction {\n workflow_stage: {\n uid: string\n comment?: string\n due_date?: string\n assigned_to?: Array<{ uid: string; name: string; email: string }>\n notify?: boolean\n }\n}\n\nexport class EntriesClient {\n constructor(private readonly http: ContentstackHttpClient) {}\n\n private basePath(ctUid: string): string {\n return `/content_types/${ctUid}/entries`\n }\n\n list(ctUid: string, opts?: EntryListOptions): AsyncIterable {\n return paginate(\n async (skip, limit) => {\n const params: Record = {\n skip: String(skip),\n limit: String(limit),\n }\n if (opts?.locale) params.locale = opts.locale\n if (opts?.include_publish_details) params.include_publish_details = \"true\"\n if (opts?.include_workflow) params.include_workflow = \"true\"\n if (opts?.include_count) params.include_count = \"true\"\n if (opts?.query) params.query = JSON.stringify(opts.query)\n if (opts?.asc) params.asc = opts.asc\n if (opts?.desc) params.desc = opts.desc\n\n const response = await this.http.get<{ entries: Entry[]; count?: number }>(\n this.basePath(ctUid),\n params,\n )\n return { items: response.data.entries ?? [], count: response.data.count }\n },\n { limit: opts?.limit },\n )\n }\n\n async listAll(ctUid: string, opts?: EntryListOptions): Promise {\n return collectAll(this.list(ctUid, opts))\n }\n\n async get(ctUid: string, entryUid: string, opts?: EntryGetOptions): Promise {\n const params: Record = {}\n if (opts?.locale) params.locale = opts.locale\n if (opts?.include_publish_details) params.include_publish_details = \"true\"\n if (opts?.include_workflow) params.include_workflow = \"true\"\n if (opts?.version) params.version = String(opts.version)\n\n const response = await this.http.get<{ entry: Entry }>(\n `${this.basePath(ctUid)}/${entryUid}`,\n Object.keys(params).length > 0 ? params : undefined,\n )\n return response.data.entry\n }\n\n async create(ctUid: string, data: Partial): Promise {\n const response = await this.http.post<{ entry: Entry }>(this.basePath(ctUid), { entry: data })\n return response.data.entry\n }\n\n async update(ctUid: string, entryUid: string, data: Partial): Promise {\n const response = await this.http.put<{ entry: Entry }>(`${this.basePath(ctUid)}/${entryUid}`, {\n entry: data,\n })\n return response.data.entry\n }\n\n async delete(ctUid: string, entryUid: string, opts?: { locale?: string }): Promise {\n let path = `${this.basePath(ctUid)}/${entryUid}`\n if (opts?.locale) path += `?locale=${encodeURIComponent(opts.locale)}`\n await this.http.delete(path)\n }\n\n async publish(ctUid: string, entryUid: string, data: PublishAction): Promise {\n await this.http.post(`${this.basePath(ctUid)}/${entryUid}/publish`, { entry: data })\n }\n\n async unpublish(ctUid: string, entryUid: string, data: PublishAction): Promise {\n await this.http.post(`${this.basePath(ctUid)}/${entryUid}/unpublish`, { entry: data })\n }\n\n async localize(ctUid: string, entryUid: string, data: Record): Promise {\n const response = await this.http.post<{ entry: Entry }>(\n `${this.basePath(ctUid)}/${entryUid}/localize`,\n { entry: data },\n )\n return response.data.entry\n }\n\n async setWorkflowStage(\n ctUid: string,\n entryUid: string,\n data: WorkflowStageAction,\n ): Promise {\n await this.http.post(`${this.basePath(ctUid)}/${entryUid}/workflow`, data)\n }\n\n async references(ctUid: string, entryUid: string): Promise {\n const response = await this.http.get<{ references: unknown[] }>(\n `${this.basePath(ctUid)}/${entryUid}/references`,\n )\n return response.data.references ?? []\n }\n\n async languages(ctUid: string, entryUid: string): Promise {\n const response = await this.http.get<{ locales: unknown[] }>(\n `${this.basePath(ctUid)}/${entryUid}/languages`,\n )\n return response.data.locales ?? []\n }\n\n async versions(ctUid: string, entryUid: string): Promise {\n const response = await this.http.get<{ versions: unknown[] }>(\n `${this.basePath(ctUid)}/${entryUid}/versions`,\n )\n return response.data.versions ?? []\n }\n\n async import(\n ctUid: string,\n data: Record,\n opts?: { locale?: string; overwrite?: boolean },\n ): Promise {\n let path = `${this.basePath(ctUid)}/import`\n const params: string[] = []\n if (opts?.locale) params.push(`locale=${encodeURIComponent(opts.locale)}`)\n if (opts?.overwrite) params.push(\"overwrite=true\")\n if (params.length > 0) path += `?${params.join(\"&\")}`\n\n const response = await this.http.post<{ entry: Entry }>(path, data)\n return response.data.entry\n }\n}\n","// @timbenniks/contentstack-platform-sdk — CMA EnvironmentsClient\n\nimport type { ContentstackHttpClient } from \"../http/client.js\"\nimport { CrudClient } from \"./base-client.js\"\nimport type { Environment } from \"./types.js\"\n\nexport class EnvironmentsClient extends CrudClient {\n constructor(http: ContentstackHttpClient) {\n super(http, {\n basePath: \"/environments\",\n singularKey: \"environment\",\n pluralKey: \"environments\",\n })\n }\n}\n","// @timbenniks/contentstack-platform-sdk — CMA ExtensionsClient\n\nimport type { ContentstackHttpClient } from \"../http/client.js\"\nimport { CrudClient } from \"./base-client.js\"\nimport type { Extension } from \"./types.js\"\n\nexport class ExtensionsClient extends CrudClient {\n constructor(http: ContentstackHttpClient) {\n super(http, { basePath: \"/extensions\", singularKey: \"extension\", pluralKey: \"extensions\" })\n }\n\n async upload(form: FormData): Promise {\n const response = await this.http.upload<{ extension: Extension }>(\"/extensions\", form)\n return response.data.extension\n }\n}\n","// @timbenniks/contentstack-platform-sdk — CMA GlobalFieldsClient\n\nimport type { ContentstackHttpClient } from \"../http/client.js\"\nimport { CrudClient } from \"./base-client.js\"\nimport type { GlobalField } from \"./types.js\"\n\nexport class GlobalFieldsClient extends CrudClient {\n constructor(http: ContentstackHttpClient) {\n super(http, {\n basePath: \"/global_fields\",\n singularKey: \"global_field\",\n pluralKey: \"global_fields\",\n })\n }\n\n async export(uid: string): Promise {\n const response = await this.http.get<{ global_field: GlobalField }>(\n `/global_fields/${uid}/export`,\n )\n return response.data.global_field\n }\n\n async import(data: Record): Promise {\n const response = await this.http.post<{ global_field: GlobalField }>(\n \"/global_fields/import\",\n data,\n )\n return response.data.global_field\n }\n}\n","// @timbenniks/contentstack-platform-sdk — CMA LabelsClient\n\nimport type { ContentstackHttpClient } from \"../http/client.js\"\nimport { CrudClient } from \"./base-client.js\"\nimport type { Label } from \"./types.js\"\n\nexport class LabelsClient extends CrudClient