@ax-hub/sdk 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+## [1.0.0-rc.1] — 2026-05-21
+
+SDK master-plan implementation across foundation, identity/tenants, authz/audit/gateway, data DSL, codegen, webhook/idempotency, and DevEx gates.
+
+### Breaking
+
+- Build output is now minified to keep the ESM main bundle under the 100KB budget.
+
+### Migration
+
+```ts
+// Before (0.x aliases, kept for compatibility until RC cleanup)
+await sdk.identity.issuePersonalAccessToken({ name: 'ci' })
+
+// Preferred
+await sdk.identity.pat.issue({ name: 'ci' })
+```
+
+Run `node --experimental-strip-types codemods/0.x-to-1.0.ts <files...>` for textual alias migration.
+
+### Added
+
+- `sdk.tenant(slug)` / `sdk.tenant(slug).app(appSlug)` scoped clients.
+- `sdk.tenants` members, invitations, email domains, icon upload.
+- `sdk.identity.pat`, `oauth`, `oidc`, `deviceCode`, `idp`, and `systemOAuthClients` sub-namespaces.
+- `sdk.authz`, `sdk.audit`, `sdk.gateway`, and `sdk.data` bounded-context clients.
+- Type-safe data DSL: `defineSchema`, `where`, `and/or/not`, `raw`, `escapeLike`.
+- Webhook HMAC verification with timestamp tolerance and replay cache.
+- Codegen outputs under `codegen/generated/` plus route inventory drift checks.
+- DevEx utilities: `bench:tthw`, `check:size`, minimal `ax-hub-sdk doctor`, opt-in E2E smoke test, README-ko, examples.
+
+### Verification
+
+- `npm run typecheck`
+- `npm run test` — 232 passed, 1 opt-in E2E skipped
+- `npm run build`
+- `npm run generate`
+- `npm run extract-codes`
+- `npm run route-inventory-diff`
+- `npm run check:size`
+
+## [0.2.0] — 2026-05-15
+
+apps SDK expansion. Phase 1 aha demo (`apps.create` + `deployments` + auth) extends to publication workflow, social loop (likes/comments/access), schema admin (tables/grants), oauth-clients, git connection, icon upload, and admin review namespace. 28 / 28 apps backend context endpoints covered.
+
+### Added
+
+- **Publication workflow**: `sdk.apps.publication.submit/list/unpublish` (owner) + `sdk.publicationRequests.get/approve/reject/listPending` (reviewer/admin) — full state machine for `draft → pending_review → approved → public`.
+- **Social loop**: `sdk.apps.likes.like/unlike/me` (idempotent — backend returns `inserted` / `deleted` booleans), `sdk.apps.comments.add/list/listAll/delete` (1-500 char client-side validation, paginated iterator), `sdk.apps.access.grant/revoke/me` (self-grant; `me()` returns `null` for 404).
+- **Schema admin**: `sdk.apps.tables.list/create/delete/addColumn/dropColumn/listGrants/addGrant/revokeGrant`. Table name regex `^[a-z][a-z0-9_]{0,62}$` validated client-side via `validateTableName`.
+- **OAuth clients**: `sdk.apps.oauthClients.create/delete`. `create` returns `clientSecret` raw — **surfaced exactly once**, store immediately (PAT pattern).
+- **Git connection**: `sdk.apps.git.connect/installStart` — GitHub App install flow + repo binding.
+- **App lifecycle additions**: `sdk.apps.permanent` (hard-purge soft-deleted app), `sdk.apps.signIconUploadURL`/`signIconDarkUploadURL` (presigned PUT), `sdk.apps.listMine` (apps caller has access to, distinct from tenant-scoped `list`).
+- **Error subclasses** (19 new): `AlreadyRevokedError`, `AlreadySettledError`, `AlreadyActiveError`, `AlreadyInactiveError`, `AlreadyAccessedError`, `NotDeletedError`, `LastAdminError`, `PendingExistsError`, `InvalidStateTransitionError`, `SchemaNameTakenError`, `DomainTakenError`, `DuplicateError`, `NotMemberError`, `NotAllowedError`, `InvalidValueError`, `RequiredError`, `EmptyError`, `BadRequestError`, `AppUnavailableError`. All mapped from backend `codes.go` (b7d2e6a).
+- **`validateTableName`** helper in `src/utils/slug.ts`.
+- **`examples/social-app-demo.ts`** — end-to-end publication workflow + social loop demo.
+
+### Coverage
+
+- 28 / 28 apps backend context endpoints (100%).
+- 9 new integration test files: publication, access, likes, comments, tables, oauth-clients, git, publication-requests, plus apps-flow extensions.
+- Test count: 73 → 130+ tests.
+
+### NOT in this release
+
+- **Data API** (`/data/{tenantSlug}/{appSlug}/{table}/*`) — runtime CRUD against tables you created via `tables.*`. Backend dispatcher Phase 2 dependency. Workaround in v0.2: use `sdk.http.request` directly for raw fetch. Tracked for v0.2.2.
+- **Tenants context** (`sdk.tenants.*`, `categories`) — next PR.
+- **Identity OAuth admin** — Identity BC namespace, separate PR.
+- MCP server bundle (v1.1), browser bundle (v1.2).
+
+### Backend dependencies
+
+- Pinned against backend `main` HEAD `b7d2e6a` (apps dispatcher on spec 278 신형식). `schema` BC dispatcher legacy — `tables.*` relies on HTTP-status fallback for category dispatch; specific subclass mapping may miss until backend completes Phase 2 dispatcher migration.
+
+---
+
+## [0.1.0] — 2026-05-14
+
+Initial Phase 1 development. v0.1.0 release.
+
+### Added
+
+- `AxHubClient` with PAT and JWT auth modes (+ JWT refresh dedupe)
+- Backend wrapped envelope error dispatch (spec 278 land): 9 category base classes (`ValidationError`, `UnauthenticatedError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `PreconditionFailedError`, `RateLimitedError`, `InternalServerError`, `UnavailableError`) + 10 specific code subclasses (`SlugTakenError`, `TokenExpiredError`, `NotAdminError`, `PermanentlyDeletedError`, …)
+- OAuth RFC 6749 separate dispatch path (`OAuthError` + specific codes for Device Flow)
+- SSE async iterator with client-side dedupe + gap detection (Phase 0 finding: backend hub.go ignores `Last-Event-ID`)
+- Pagination `listAll` async iterator with drift event emission
+- Rate limit handling — `Retry-After` honor, `'sleep' | 'throw'` strategies
+- `X-Request-Id` (ULID) auto-injection per request, surfaced on every `AxHubError.requestId`
+- Tenant scoping — `defaultTenantSlug`, `withTenant`, `TenantSlugRequiredError`
+- Resources: `sdk.apps.*` (CRUD + env-vars, directory split), `sdk.deployments.*` (lifecycle + 3 SSE streams), `sdk.identity.*` (PAT issuance, me)
+- Injectable logger interface + Authorization/X-Api-Key/Cookie redaction
+- Dual ESM/CJS build via tsup, strict TypeScript, vitest test runner
+
+### Coverage
+
+- 73 tests (60 unit + 13 integration)
+- 18 / 77 backend endpoints (aha demo path). Phase 2 fills out remaining 59.
+
+### Known limitations
+
+- Backend `Last-Event-ID` on SSE not honored; SDK dedupes + emits `GapDetectedEvent`. Backend follow-up issue tbd.
+- Backend `Idempotency-Key` not supported; SDK does not auto-inject and refuses to retry POST/PATCH/DELETE.
+- MCP server bundle (v1.1), browser bundle (v1.2), CLI tool, OpenTelemetry native: deferred.
+- `codegen/extract-codes.ts` was still unwired — `src/errors/code-map.ts` was a hand-written stub mirroring backend `codes.go` registry.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 jocoding-ax-partners
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing permissions
+   and limitations under the License.

package/README.md

@@ -0,0 +1,276 @@
+# @ax-hub/sdk
+
+agent-first Node.js SDK for AX Hub. Designed for Claude, Codex, and other coding agents — one client, 8 bounded contexts, typed errors, async iterators for SSE streams, generated drift inventory, and no hidden Korean substring matching.
+
+## I want to...
+
+| Goal | Section |
+|------|---------|
+| make my first API call | [Magic Moment](#magic-moment) |
+| scope work to a tenant/app | [Tenant Scoping](#tenant-scoping) |
+| choose JWT vs PAT or OAuth | [Authentication](#authentication) |
+| query dynamic tables | [Dynamic Data + Query DSL](#dynamic-data--query-dsl) |
+| debug an error | [Errors & Debugging](#errors--debugging) |
+| upgrade from 0.x | [Migration & Upgrade](#migration--upgrade) |
+
+## Magic Moment
+
+```ts
+import { AxHubClient, defineSchema, where } from '@ax-hub/sdk'
+
+const sdk = new AxHubClient({
+  token: process.env.AX_HUB_PAT!,
+  tokenType: 'pat',
+})
+
+const crm = sdk.tenant('acme').app('crm')
+const Orders = defineSchema({
+  table: 'orders',
+  columns: {
+    id: 'uuid',
+    status: { type: 'enum', values: ['paid', 'pending'] as const },
+    total: 'number',
+  },
+})
+
+const app = await sdk.tenant('acme').apps.create({ slug: 'crm', name: 'CRM' })
+const paid = await crm.data.table(Orders).list({
+  where: where(Orders.cols.status).eq('paid'),
+})
+
+console.log(app.slug, paid.total)
+```
+
+5분 안에 첫 app ship 가능.
+
+## Resource Catalog
+
+| Namespace | Methods |
+|-----------|---------|
+| `sdk.apps` | `create`, `list`, `listAll`, `get`, `update`, `delete`, `permanent`, `listMine`, `signIconUploadURL`, `signIconDarkUploadURL`, `listEnvVars`, `setEnvVar`, `getEnvVar`, `deleteEnvVar` |
+| `sdk.apps.publication` | `submit`, `list`, `unpublish` (owner-scoped lifecycle) |
+| `sdk.apps.access` | `grant`, `revoke`, `me` (self-grant; `me()` returns `null` on 404) |
+| `sdk.apps.likes` | `like`, `unlike`, `me` (idempotent — backend returns `inserted`/`deleted` booleans) |
+| `sdk.apps.comments` | `add`, `list`, `listAll`, `delete` (1-500 char client-side validation) |
+| `sdk.apps.oauthClients` | `create` (⚠ `clientSecret` surfaced ONCE), `delete` |
+| `sdk.apps.git` | `connect`, `installStart` (GitHub App install flow) |
+| `sdk.apps.categories` | tenant category CRUD |
+| `sdk.apps.discover` | catalog search facade |
+| `sdk.apps.templates` | app template listing |
+| `sdk.apps.tables` | `list`, `create`, `delete`, `addColumn`, `dropColumn`, `listGrants`, `addGrant`, `revokeGrant` (schema admin) |
+| `sdk.publicationRequests` | `get`, `approve`, `reject`, `listPending` (reviewer/admin namespace — separate from owner-scoped `sdk.apps.publication`) |
+| `sdk.deployments` | `create`, `list`, `listAll`, `get`, `cancel`, `rollback`, `streamBuildLogs`, `streamPodLogs`, `streamPodEvents` |
+| `sdk.identity` | `pat.*`, `oauth.*`, `oidc.*`, `deviceCode.*`, `idp.*`, `systemOAuthClients.*`, `me` |
+| `sdk.tenants` | tenant CRUD, members, invitations, email domains, icon upload |
+| `sdk.authz` | PBAC tags/subjects/grants + `evaluator.decide/decideMany` |
+| `sdk.audit` | events, integrity check, anonymize, server-only emit |
+| `sdk.gateway` | engines, connectors, resources, query run/stream |
+| `sdk.data` | `/data/{tenantSlug}/{appSlug}/{table}` CRUD + bulk + typed DSL |
+
+The committed generated route inventory currently tracks the pinned backend swagger snapshot; future backend-only BCs are surfaced by `npm run route-inventory-diff`.
+
+### `sdk.apps.list` vs `sdk.apps.listMine`
+
+- `list()` — returns apps in the **resolved tenant** (via `defaultTenantSlug` or `withTenant`). Tenant-scoped.
+- `listMine()` — returns apps the **caller has been granted access to** (regardless of tenant ownership). Useful for per-user "my dashboard" views. Wraps `GET /users/me/apps`.
+
+### `sdk.apps.publication` vs `sdk.publicationRequests`
+
+- `sdk.apps.publication.*` — **owner-scoped**: submit/list/unpublish own app. App ID is the input.
+- `sdk.publicationRequests.*` — **reviewer/admin-scoped**: get/approve/reject any publication request, list all pending. Publication request ID is the input. Requires `publication_reviewer` (approve/reject) or platform admin (`listPending`) roles.
+
+### `sdk.apps.oauthClients.create` — raw secret surfaced once
+
+```ts
+const c = await sdk.apps.oauthClients.create('app_abc', {
+  name: 'web',
+  redirectUris: ['https://myapp.com/cb'],
+  scopes: ['read', 'write'],
+})
+storeSecret(c.clientSecret) // <-- this is your ONLY chance. Backend keeps only a hash.
+//                              Subsequent list/get methods will NOT include the secret.
+```
+
+Lose `clientSecret`? Delete the client and create a new one.
+
+## Tenant Scoping
+
+Prefer scoped clients in examples:
+
+```ts
+const acme = sdk.tenant('acme')
+await acme.apps.create({ slug: 'crm', name: 'CRM' })
+await acme.app('crm').tables.inspect('orders')
+await acme.app('crm').data.table('orders').list()
+```
+
+Flat/root APIs remain available for non-tenant routes (`sdk.identity.oauth.exchangeCode`, `sdk.identity.oidc.jwks`, `sdk.identity.me`) and for backwards compatibility. There is no deprecation warning for flat calls.
+
+## Authentication
+
+**PAT (recommended for agents)** — single token, immutable, sent as `X-Api-Key` on data-ring requests.
+
+```ts
+const sdk = new AxHubClient({ baseUrl, token, tokenType: 'pat' })
+```
+
+**JWT with refresh** — caller-provided refresh callback; concurrent 401s share a single in-flight refresh.
+
+```ts
+const refreshClient = new AxHubClient({ baseUrl, token: jwt, tokenType: 'jwt' })
+const sdk = new AxHubClient({
+  baseUrl,
+  token: jwt,
+  tokenType: 'jwt',
+  onRefresh: async () => (await refreshClient.identity.oauth.refreshTokens({ refreshToken })).accessToken,
+})
+```
+
+### OAuth Two Worlds
+
+- `sdk.apps.oauthClients` — an app acts as IdP for its own external users.
+- `sdk.identity.systemOAuthClients` — platform/system OAuth clients for AX Hub delegation.
+
+## Dynamic Data + Query DSL
+
+`apps.tables.*` owns DDL. `data.table(schema)` owns runtime CRUD with PAT/data-ring auth:
+
+```ts
+const Orders = defineSchema({
+  table: 'orders',
+  columns: { status: { type: 'enum', values: ['paid', 'pending'] as const }, total: 'number' },
+})
+const page = await sdk.tenant('acme').app('crm').data.table(Orders).list({
+  where: and(where(Orders.cols.status).eq('paid'), where(Orders.cols.total).gt(100)),
+})
+```
+
+`like.contains/startsWith/endsWith` automatically escapes `%`, `_`, and `\\`. Use `raw()` only when you intentionally own SQL-like syntax.
+
+## Errors & Debugging
+
+### Error Types
+
+All `/api/v1/*` 4xx/5xx responses become typed `AxHubError` subclasses. `error.category` (9 enum from backend spec 278) drives base class, `error.code` selects specific subclass.
+
+| Class | Status | `retryable` | Hint |
+|-------|--------|-------------|------|
+| `UnauthenticatedError` (+ `TokenMissingError`, `TokenExpiredError`, `TokenInvalidError`) | 401 | true (re-auth) | refresh token |
+| `PermissionDeniedError` (+ `NotAdminError`, `ForbiddenError`, `NotMemberError`, `NotAllowedError`) | 403 | false | request grant |
+| `NotFoundError` (+ `PermanentlyDeletedError`, `InvitationExpiredError`) | 404 / 410 | false | abort |
+| `ConflictError` (+ `SlugTakenError`, `AlreadyMemberError`, `AlreadyDeletedError`, `AlreadyRevokedError`, `AlreadySettledError`, `AlreadyAccessedError`, `PendingExistsError`, `InvalidStateTransitionError`, `SchemaNameTakenError`, `DomainTakenError`, `NotDeletedError`, `LastAdminError`, `DuplicateError`) | 409 | false | try different value |
+| `ValidationError` (+ `InvalidValueError`, `RequiredError`, `EmptyError`, `BadRequestError`) | 400 / 422 | false | fix `fields[]` |
+| `PreconditionFailedError` | 412 | false | reconcile state |
+| `RateLimitedError` | 429 | true | sleep `retry.afterMs` |
+| `InternalServerError` | 500 | **false** | escalate to human |
+| `UnavailableError` (+ `AppUnavailableError`) | 502 / 503 / 504 | true | exponential backoff |
+| `NetworkError`, `TimeoutError`, `DecodeError`, `AbortError` | — | varies | — |
+| `OAuthError` (+ specific RFC 6749 codes) | — | varies (per code) | — |
+
+```ts
+try {
+  await sdk.apps.create({ slug: 'taken', name: 'X' })
+} catch (e) {
+  if (e instanceof SlugTakenError) {
+    // retry with different slug; e.fields[0].name === 'slug'
+  }
+}
+```
+
+## Streaming (SSE)
+
+```ts
+const controller = new AbortController()
+for await (const ev of sdk.deployments.streamBuildLogs(appId, deploymentId, { signal: controller.signal })) {
+  if (ev.type === 'item') {
+    console.log(ev.value.line)
+    if (ev.value.line.includes('ERROR')) controller.abort()
+  } else if (ev.type === 'gap') {
+    console.warn('lost some log frames since', ev.sinceId)
+  }
+}
+```
+
+Single-consumer iterator. Calling `for await` twice throws `StreamConsumedError`. Backend currently re-replays the ring buffer on every reconnect (200 events cap), so SDK does client-side dedupe + gap detection. `Last-Event-ID` header is sent for forward compatibility.
+
+## Webhook Handling
+
+```ts
+import { verifyWebhook } from '@ax-hub/sdk'
+
+const result = verifyWebhook({
+  rawBody,
+  secret: process.env.AX_HUB_WEBHOOK_SECRET!,
+  signature: headers.get('x-ax-hub-signature')!,
+  timestamp: headers.get('x-ax-hub-timestamp') ?? undefined,
+})
+```
+
+Verification uses HMAC SHA-256, timing-safe comparison, timestamp tolerance, and optional replay cache.
+
+## Idempotency
+
+`HttpClient` supports per-call `idempotencyKey` and generated `Idempotency-Key` on explicitly idempotent SDK calls. Empty keys fail fast with typed validation.
+
+## Codegen workflow
+
+Generated inventory is committed under `codegen/generated/`.
+
+```bash
+npm run generate
+npm run extract-codes
+npm run route-inventory-diff
+```
+
+CI fails if swagger route inventory and generated files drift.
+
+## Migration & Upgrade
+
+Every pre-1.0 minor must include `CHANGELOG.md` `Migration` notes. 0.x aliases are kept through 0.5 and removed at 1.0 RC with `codemods/0.x-to-1.0.ts`.
+
+## Concepts
+
+- **Tenant scoping.** `defaultTenantSlug` on constructor, `client.withTenant(slug)` for per-call switching, `TenantSlugRequiredError` when ambiguous.
+- **Pagination.** `list({ pageSize, cursor })` for single page. `listAll({ pageSize })` for async iterator that yields `{type:'item', value:T}` or `{type:'drift', addedSince}` when the backend's total grows mid-iteration.
+- **Rate limiting.** Default strategy `'sleep'` — SDK honors `Retry-After` and silently retries. Use `rateLimitStrategy: 'throw'` to surface `RateLimitedError(retry.afterMs)` to caller.
+- **Request correlation.** SDK auto-generates `X-Request-Id` (ULID) on every request. Backend echoes it OR replaces with its own `req_xxx` prefix if absent. `AxHubError.requestId` always present.
+- **Token redaction.** Authorization / X-Api-Key / Cookie are always replaced with `***REDACTED***` in debug logs and `Error.toJSON()` output.
+- **Debug mode.** `new AxHubClient({ debug: true, logger: pino() })` — opt-in structured request/response logging. Default off.
+- **Language.** Backend `error.message` is Korean (user-facing) by design. `error.code` and `error.category` are machine-readable (snake_case English) and stable across translations. Agents should branch on `code`/`category`; humans see the Korean `message`. English-only message support is deferred (see backend roadmap, no SDK changes required when added).
+
+## Branded ID types (optional)
+
+For callers wanting compile-time guards against mixing IDs (e.g., passing `tenantId` where `appId` is expected):
+
+```ts
+import { type AppId, type DeploymentId, asAppId } from '@ax-hub/sdk'
+
+const appId: AppId = asAppId('app_abc')
+const depId: DeploymentId = asDeploymentId('dep_xyz')
+
+await sdk.deployments.create(appId)  // OK
+// await sdk.deployments.create(depId)  // type error — DeploymentId ≠ AppId
+```
+
+The SDK's own methods still accept plain `string` — branded types are opt-in for caller code.
+
+## Performance
+
+SDK overhead (excluding network + backend time), measured via `npm run bench` against an in-memory fake fetch:
+
+| Operation | p99 |
+|-----------|-----|
+| `apps.create` happy path | < 0.08ms |
+| `apps.create` 409 conflict (error dispatch) | < 0.08ms |
+| Error dispatch alone (wrapped envelope → typed subclass) | < 0.005ms |
+| SSE frame parser (100 frames / chunk) | < 0.07ms |
+
+Target was < 10ms p99 — 100x+ headroom in every path.
+
+## Backend dependency
+
+Pinned against backend spec 278 (`feat/278-structured-errors`, landed 2026-05-14). Re-generate types via `npm run generate` + `npm run extract-codes` after backend swagger updates. Once backend completes Phase 2 dispatcher migration (all 6 dispatchers using the structured `ErrXxx → category / code` description format), `extract-codes` auto-syncs the full code-map; until then `src/errors/code-map.ts` is hand-maintained against backend `codes.go`.
+
+## License
+
+UNLICENSED (TBD — see `.plan/design.md` Open Question 2).

package/dist/cli/doctor.cjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+'use strict';var K=m;(function(J,Y){var U=m,k=J();while(!![]){try{var A=parseInt(U(0x19d))/(-0x1576+-0x40*-0x42+-0x1f*-0x29)*(parseInt(U(0x1b2))/(-0x1*0x2257+-0x675+0x6cd*0x6))+parseInt(U(0x1a1))/(-0xc9*-0x1+0x8f7+-0x3*0x33f)+parseInt(U(0x1c8))/(0x16b2+0x1e2b*-0x1+0x77d)*(parseInt(U(0x1b4))/(-0x7*0x17e+0x1*-0x2c2+0xd39))+parseInt(U(0x1a9))/(0x2d3+-0x3*0xa81+-0x32*-0x93)+-parseInt(U(0x19c))/(-0x697+0x742+0x4*-0x29)+-parseInt(U(0x1a4))/(0x1874+0x419*0x8+0x7*-0x82c)+parseInt(U(0x19f))/(-0x2*0x653+-0x22d0+0x2f7f);if(A===Y)break;else k['push'](k['shift']());}catch(L){k['push'](k['shift']());}}}(C,-0x6d93*-0x43+0x16dec0+-0x247673));function m(J,Y){J=J-(-0x5a8+0x1f36+-0x17f9);var k=C();var A=k[J];if(m['MZZRHb']===undefined){var e=function(X){var u='abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789+/=';var D='',y='',F=D+e,U=(''+function(){return-0x13f1+0x1fed+-0xbfc;})['indexOf']('\x0a')!==-(0x1*0x96d+-0x1*0x1471+0xb05);for(var K=-0x959+-0x2701+-0x305a*-0x1,b,B,Q=-0x79c*0x1+-0x1575+0x1d11;B=X['charAt'](Q++);~B&&(b=K%(0x2*-0xdb+-0x510+-0x1*-0x6ca)?b*(0x66b*-0x1+0x2438+-0x1d8d)+B:B,K++%(-0x3+-0x6d*-0x57+0x2504*-0x1))?D+=U||F['charCodeAt'](Q+(0xde4+0x5*0x419+-0x2257))-(0x4*-0x9be+-0xf*0x272+0x4bb0)!==-0x227a+-0x1*0x1371+0x6b*0x81?String['fromCharCode'](0xe48+-0x292+0xab7*-0x1&b>>(-(0x2111+-0x340+-0x1dcf)*K&0x20be+-0x2*0xd67+0x2*-0x2f5)):K:0x11*-0x1b2+0x1c33+-0x3*-0x35){B=u['indexOf'](B);}for(var p=-0x2a*0xa2+0x2*-0x2ad+0x43*0x7a,w=D['length'];p<w;p++){y+='%'+('00'+D['charCodeAt'](p)['toString'](-0x1649*0x1+0xd43+0x916*0x1))['slice'](-(0xefd+-0x729*-0x2+0xd*-0x241));}return decodeURIComponent(y);};m['iioEhj']=e,m['EhJprm']={},m['MZZRHb']=!![];}var L=k[0x201*0x13+-0x81*-0x7+-0x299a],E=J+L,i=m['EhJprm'][E];if(!i){var X=function(u){this['gjJaxH']=u,this['HddUpS']=[0x180f+0x1*0x1136+-0x2944,-0x162e+0x2*-0x8ae+0x278a,0x15a1+-0x1*-0xea4+-0xf*0x26b],this['VnzanO']=function(){return'newState';},this['fsMFAg']='\x5cw+\x20*\x5c(\x5c)\x20*{\x5cw+\x20*',this['bptJlz']='[\x27|\x22].+[\x27|\x22];?\x20*}';};X['prototype']['nZIBeu']=function(){var u=new RegExp(this['fsMFAg']+this['bptJlz']),D=u['test'](this['VnzanO']['toString']())?--this['HddUpS'][-0x1dd4+0x233c+-0x567]:--this['HddUpS'][-0x6b*0x1f+-0x29*0xe4+0x3179];return this['sedVSm'](D);},X['prototype']['sedVSm']=function(u){if(!Boolean(~u))return u;return this['UhIXIz'](this['gjJaxH']);},X['prototype']['UhIXIz']=function(u){for(var D=-0x596+0x3*-0xaad+0x259d,y=this['HddUpS']['length'];D<y;D++){this['HddUpS']['push'](Math['round'](Math['random']())),y=this['HddUpS']['length'];}return u(this['HddUpS'][0x6c1+0xc57+0xbc*-0x1a]);},(''+function(){return 0x1c8a*-0x1+0xcb*0x29+-0x1*0x3f9;})['indexOf']('\x0a')===-(-0x200a+0x23d2+-0x3c7)&&new X(m)['nZIBeu'](),A=m['iioEhj'](A),m['EhJprm'][E]=A;}else A=i;return A;}var fs=require('fs'),path=require(K(0x1c7)),_documentCurrentScript=typeof document!==K(0x1b3)+K(0x1bf)?document[K(0x1bc)+K(0x1aa)+'ipt']:null;function t(k=process[K(0x1a5)]()){var b=K,A={'KkabK':function(X,u,D){return X(u,D);},'pbdnl':function(X){return X();},'UWxrs':b(0x1c9)+b(0x1b0)+b(0x1c0)+b(0x1cb),'ixUvX':b(0x1c5)+b(0x1b1)+'ts'},L=(function(){var X=!![];return function(u,D){var y=X?function(){var B=m;if(D){var F=D[B(0x1bd)](u,arguments);return D=null,F;}}:function(){};return X=![],y;};}()),E=A[b(0x1c6)](L,this,function(){var Q=b;return E[Q(0x1ba)+Q(0x1a7)]()['searc'+'h'](Q(0x1a6)+Q(0x1a3)+'+$')['toStr'+Q(0x1a7)]()[Q(0x1c3)+Q(0x19a)+'r'](E)['searc'+'h']('(((.+'+Q(0x1a3)+'+$');});A[b(0x1bb)](E);let i=[{'name':b(0x1ca)+b(0x1ae)+'on','ok':fs['exist'+b(0x19e)](path[b(0x1be)+'ve'](k,b(0x1ca)+b(0x1ae)+'on'))},{'name':b(0x1c9)+b(0x1b0)+b(0x1c0)+'.json','ok':fs['exist'+'sSync'](path['resol'+'ve'](k,A[b(0x1c1)]))},{'name':A[b(0x197)],'ok':fs[b(0x198)+'sSync'](path['resol'+'ve'](k,b(0x1c5)+b(0x1b1)+'ts'))}];return{'ok':i['every'](X=>X['ok']),'checks':i};}function C(){var p=['odq0nZqYngvyzNf5uW','y3DK','kcGOlIS','Aw5N','C3jJ','mZe0nZq5ohrHsLjOvG','BNrty3i','zxHPDa','D3jPDgu','CI5JANm','z2uUANm','C3rKB3u','zw4VC3C','BMrLEc4','mZu3mdC0sxLmBMDy','Dw5Kzwy','nJK0nda5nxDlr3vfsq','vvjm','CNvUrg8','Cgf0Afq','B0zPBgu','AhjLzG','Dg9tDhi','CgjKBMW','y3vYCMu','yxbWBhK','CMvZB2W','Aw5Lza','ywDNzxi','vvD4CNm','u0nssva','y29UC3q','yMfZzvu','C3jJl2K','s2THyKS','Cgf0Aa','ngLlCxb3zq','y29KzwC','CgfJA2e','lMPZB24','yxjNDG','DgfNtMe','AxHvDLG','zxHPC3q','zg9JDg8','CNvJDg8','Dg9vCha','ote5oty1mLrytu5zEq','mvDeEe9kEa','C1n5BMm','mJCZndqXnM5AEhvnDG','C3rYAw4','mJG4ota0nwLNBxjIrW','y3rVCG','ksSPkYK'];C=function(){return p;};return C();}if((typeof document===K(0x1b3)+K(0x1bf)?require('u'+'rl')[K(0x1b7)+K(0x1b8)+K(0x1b5)](__filename)[K(0x1b9)]:_documentCurrentScript&&_documentCurrentScript[K(0x196)+'me'][K(0x19b)+'erCas'+'e']()===K(0x1c2)+'T'&&_documentCurrentScript[K(0x1a8)]||new URL(K(0x199)+K(0x1ad),document[K(0x1c4)+'RI'])[K(0x1b9)])==='file:'+'//'+process[K(0x195)][-0x21fc+0x1d21+0x4dc]){let e=t();process[K(0x1af)+'t'][K(0x1ac)](JSON[K(0x1a0)+'gify'](e,null,0x1*0xfd7+0x33*-0x4f+-0x18)+'\x0a'),process[K(0x1ab)](e['ok']?0xd43+0xbf+0x701*-0x2:0xefd+-0x729*-0x2+0x3e*-0x79);}exports[K(0x1b6)+K(0x1a2)]=t;

package/dist/cli/doctor.d.cts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+interface DoctorResult {
+    ok: boolean;
+    checks: Array<{
+        name: string;
+        ok: boolean;
+        detail?: string;
+    }>;
+}
+declare function runDoctor(cwd?: string): DoctorResult;
+
+export { type DoctorResult, runDoctor };

package/dist/cli/doctor.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+interface DoctorResult {
+    ok: boolean;
+    checks: Array<{
+        name: string;
+        ok: boolean;
+        detail?: string;
+    }>;
+}
+declare function runDoctor(cwd?: string): DoctorResult;
+
+export { type DoctorResult, runDoctor };

package/dist/cli/doctor.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+const K=m;function C(){const p=['CNvJDg8','mtHXBgj0CvK','nhLZA2r6vq','mJeYoduZC2Xfrg1T','y29KzwC','zw4VC3C','Dg9tDhi','y3DK','BLvev3e','lMPZB24','mw91u0nZuW','C3jJl2K','ywDNzxi','C2vHCMm','tMzYyxC','DLn1r2u','ksSPkYK','z2uUANm','CgfJA2e','D3jPDgu','C3rYAw4','A2zfzLy','zxzLCNK','mtq4nJC5nMPhzgTYAq','kcGOlIS','nJK3mdy0mgHbyMzZrq','zxHPDa','y29UC3q','C3rKB3u','mZi4mKrACxLNua','Aw5N','z0TOCu4','BMrLEc4','mJKXndCYnvfhs0TREa','zMLSztO','yxbWBhK','nZi2nty5oenKAxfqEG','mti1m1bsDe1rBW','mtGYodK1mMHgDvHIDq'];C=function(){return p;};return C();}(function(J,Y){const U=m,k=J();while(!![]){try{const A=parseInt(U(0x15e))/(-0x13d3+-0xff2*-0x2+-0xc10)*(parseInt(U(0x144))/(0x1f6+0x3*0x577+0x1ab*-0xb))+parseInt(U(0x157))/(-0x18fb+0x267b+-0xd7d)*(parseInt(U(0x156))/(-0x218d+0x1074+0x111d))+-parseInt(U(0x14e))/(0x30b*-0x3+-0x2059+0x297f*0x1)+parseInt(U(0x14a))/(0x1*-0x2597+0xdf5+0xbd4*0x2)*(-parseInt(U(0x152))/(0x6ed+-0x31*-0xa7+-0x26dd*0x1))+parseInt(U(0x153))/(0x15bd+-0x1*0x624+0xf91*-0x1)*(parseInt(U(0x155))/(-0x1*0x22a+0x1*-0x2d7+0x50a*0x1))+-parseInt(U(0x146))/(0x2e*0x3d+-0x1713+0xb7*0x11)+parseInt(U(0x151))/(-0xa*0x50+-0x3df+-0x22*-0x35);if(A===Y)break;else k['push'](k['shift']());}catch(L){k['push'](k['shift']());}}}(C,-0x7613*-0xd+0x121b6+-0x715e*-0x3));import{existsSync}from'fs';import{resolve}from'path';function t(k=process[K(0x15b)]()){const b=K,A={'vSuGe':b(0x145)+b(0x164)+'+$','Nfraw':function(X){return X();},'drEFP':b(0x13f)+'ge.js'+'on','nUDWq':function(X,u){return X(u);},'kfEfV':function(X,u,D){return X(u,D);},'gKhqN':b(0x15f)+b(0x14d)+'ts'},L=(function(){let X=!![];return function(u,D){const y=X?function(){const B=m;if(D){const F=D[B(0x150)](u,arguments);return D=null,F;}}:function(){};return X=![],y;};}()),E=L(this,function(){const Q=b;return E['toStr'+Q(0x14b)]()[Q(0x161)+'h'](A[Q(0x163)])[Q(0x15a)+'ing']()[Q(0x148)+Q(0x154)+'r'](E)[Q(0x161)+'h'](A[Q(0x163)]);});A[b(0x162)](E);let i=[{'name':A['drEFP'],'ok':existsSync(resolve(k,b(0x13f)+b(0x165)+'on'))},{'name':'codeg'+b(0x159)+b(0x160)+b(0x15d),'ok':A['nUDWq'](existsSync,A[b(0x142)](resolve,k,b(0x158)+b(0x159)+b(0x160)+b(0x15d)))},{'name':A[b(0x14c)],'ok':A[b(0x15c)](existsSync,resolve(k,A[b(0x14c)]))}];return{'ok':i[b(0x143)](X=>X['ok']),'checks':i};}if(import.meta.url===K(0x14f)+'//'+process['argv'][-0x542*0x2+-0x1*-0x269b+-0x1*0x1c16]){let e=t();process[K(0x149)+'t'][K(0x140)](JSON[K(0x141)+'gify'](e,null,0xab0+0xa1+-0xb4f)+'\x0a'),process[K(0x147)](e['ok']?0x25f0+-0x5*0x1c5+-0x1*0x1d17:0x1*0x740+0x3*0x6cb+-0x1*0x1ba0);}function m(J,Y){J=J-(0xdc2+-0xdb9+0x136);const k=C();let A=k[J];if(m['TqMdIz']===undefined){var e=function(X){const u='abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789+/=';let D='',y='',F=D+e,U=(''+function(){return 0x12e9+-0x25c*-0xd+0x3195*-0x1;})['indexOf']('\x0a')!==-(0x6*-0x623+-0x1*0xe9e+-0x3f5*-0xd);for(let K=0x10e6+0x1ea1+0x1*-0x2f87,b,B,Q=-0x445*0x9+-0xf01+0x356e;B=X['charAt'](Q++);~B&&(b=K%(-0x3*-0x89a+0x5*0x40+0x1b0a*-0x1)?b*(0x1e2f+-0x3fc+-0x7*0x3b5)+B:B,K++%(-0x1*-0x923+-0x20ff+0x17e0))?D+=U||F['charCodeAt'](Q+(0x2289+0x20c8+-0x4347*0x1))-(-0xd39+0x259a*-0x1+0x32dd)!==0x77*-0x1b+0x29*0x29+0x2*0x2fe?String['fromCharCode'](-0x1be3+0x1*-0x1f17+-0xd*-0x49d&b>>(-(-0x2597+-0xdbb+-0x447*-0xc)*K&0x1fb4+-0x76*-0x13+-0x50e*0x8)):K:-0xe97+0x138a+0xb5*-0x7){B=u['indexOf'](B);}for(let p=0x6*0x141+-0x8*0x4e+0xd9*-0x6,w=D['length'];p<w;p++){y+='%'+('00'+D['charCodeAt'](p)['toString'](-0x1bd8+-0x1*-0x1e6a+0x1*-0x282))['slice'](-(-0xc3a+-0x2*0xc1b+0x2472));}return decodeURIComponent(y);};m['XFqaSX']=e,m['yvPHNi']={},m['TqMdIz']=!![];}const L=k[-0x1*-0x15f5+0x6d*-0x1d+0x1*-0x99c],E=J+L,i=m['yvPHNi'][E];if(!i){const X=function(u){this['sdFBEk']=u,this['iIIdmQ']=[-0x1*-0xb9a+0x49*0x1f+-0x6d*0x30,-0x373+0x1*0x101e+0x439*-0x3,0x83*-0x45+-0x94*-0x6+0x1fd7],this['jowIdE']=function(){return'newState';},this['YLSjpO']='\x5cw+\x20*\x5c(\x5c)\x20*{\x5cw+\x20*',this['fPbJCH']='[\x27|\x22].+[\x27|\x22];?\x20*}';};X['prototype']['FsHeTS']=function(){const u=new RegExp(this['YLSjpO']+this['fPbJCH']),D=u['test'](this['jowIdE']['toString']())?--this['iIIdmQ'][0x4*-0x44c+-0x831+-0x156*-0x13]:--this['iIIdmQ'][0xa19+-0x21d2+0x17b9];return this['VepynN'](D);},X['prototype']['VepynN']=function(u){if(!Boolean(~u))return u;return this['pDQNcE'](this['sdFBEk']);},X['prototype']['pDQNcE']=function(u){for(let D=0x7*-0x190+-0x1643+0x2133,y=this['iIIdmQ']['length'];D<y;D++){this['iIIdmQ']['push'](Math['round'](Math['random']())),y=this['iIIdmQ']['length'];}return u(this['iIIdmQ'][-0x2bb+-0xa97+0xd52]);},(''+function(){return 0x26*0xce+-0x135*-0x15+-0x37ed;})['indexOf']('\x0a')===-(0x596+0x26e4+-0x2c79)&&new X(m)['FsHeTS'](),A=m['XFqaSX'](A),m['yvPHNi'][E]=A;}else A=i;return A;}export{t as runDoctor};