feat!: SDK 8 and provisioning-sdk 3 previews (draft, do not merge)

[pviti]

Summary

Draft — do not merge. The SDK-independent changes went to #251 (merged); only what SDK 8 needs is here.

Do not merge: the catalog points at the pkg.pr.new previews of SDK 8 (commercelayer-sdk 5259929, branch pkg-pr-new-staging1): @commercelayer/sdk 8.0.0-beta.13 and @commercelayer/provisioning-sdk 3.0.0-beta.1. To be updated with each new preview and merged once SDK 8 is on npm.

Changes in the CLI

• apiVersion: this is a version-aware SDK build: its types require apiVersion (2017-08 | 2026-05), which becomes a path segment (/api/2026-05/orders). The production API doesn't serve versioned paths yet (checked: /api/skus → 401, /api/2017-08/skus and /api/2026-05/skus → 404), so requests stay unversioned by default (the SDK omits the segment at runtime when apiVersion is undefined).
• --api-version, an operating parameter like --domain: the domain says where the requests go, and more API versions can answer there, so the version can be chosen, otherwise a default applies.
  • It is a hidden flag on every command that calls the Core API, set by CL_CLI_API_VERSION (as --domain by CL_CLI_DOMAIN), mostly to pick the environment in development (clCommand.apiVersionFlag, clApi.apiVersion in cli-core).
  • applications:login / applications:add --api-version <v> save it with the application, as the domain. The prerun hook adds it to the commands, and applications:scope keeps it. applications --extra shows an API VERSION column.
  • The default is clConfig.api.default_api_version (next to default_domain), unversioned for now. A version equal to the default isn't saved.
  • Precedence: the command's flag (or the version saved with the application), then CL_CLI_API_VERSION, then the default.
  • Tests: apiVersion precedence and default (core). The prerun hook adds the saved domain and API version only to commands that have the flags (cli, temporary config folder).
• provisioning-sdk typings workaround: its CommonJS declarations (lib/index.d.cts) end with export =, which hides the named exports (CommerceLayerProvisioningStatic, QueryParams, …) from CommonJS code. plugins/provisioning/src/sdk.ts re-exports them typed with the ESM declarations; the runtime exports are fine. To remove once the SDK is fixed (see below).
• resources: Node snippet with the named CommerceLayer import (the default export is deprecated); resource list regenerated from the SDK — from the staging1 schema, so it includes resources not yet in production (payment_*, …).
• Tests: resources:schema prints the API version (2026-05) instead of a semver.
• The SDK-independent parts (exports SDK 8 drops: resource classes, QueryArraySortable/QueryRecordSortable/QueryRecordFields; provisioning list mocks; integration on dependency changes) moved to refactor: stop using SDK exports that SDK 8 drops; integration on dependency changes #251.

To fix in the SDK

1. CommonJS declarations: lib/index.d.cts of both packages ends with // @ts-ignore + export = <default> next to named exports. TypeScript (module nodenext, CommonJS consumers) then ignores the named exports: with the provisioning-sdk preview, CommerceLayerProvisioningStatic, QueryParams, ResourceTypeLock, RequestObj are "not exported". Dropping export = (keeping export default + named exports, or the cjsInterop option of tsup) would fix it.
2. apiVersion and production: apiVersion is required by the types, but no value works against production today, where versioned paths answer 404. Either an unversioned option in the types, or 2017-08 mapped to the unversioned path.

Test plan

• Type check of every package, pnpm build, pnpm lint, check-packages, pnpm install --frozen-lockfile
• Unit suites: all passing except the 2 that need the CI credentials (cli applications:login, config:show)
• Up to date with monorepo (chore: move the release scripts to a cl-release workspace package #267–fix(metrics)!: fbt requires item IDs and prints readable results #269 included)
• CI, including Integration (live API) against cli-test-org with the preview

🤖 Generated with Claude Code