@connectedxm/admin 6.28.2 → 6.29.0

package/CLAUDE.md

@@ -0,0 +1,65 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository purpose
+
+`@connectedxm/admin` is a TypeScript SDK for the ConnectedXM Admin API. It exposes two consumption modes from a single source: raw async functions (e.g. `GetAccount`, `CreateAccount`) and React Query hooks (e.g. `useGetAccount`, `useCreateAccount`). The same file defines both — the function calls the API, the hook wraps it with React Query.
+
+A separate generated SDK (`@connectedxm/admin-sdk`, typescript-axios) is produced in `sdks/typescript/` from `openapi.json`. That output is generated, not hand-edited.
+
+## Common commands
+
+- `npm run lint` — eslint over `src/**/*.ts`
+- `npx tsc` — typecheck (the build uses tsup; tsc is configured with `noEmit`)
+- `npm run build` — bundle to `dist/` via tsup (CJS + ESM + .d.ts)
+- `npm test` — vitest (currently only a placeholder test in [tests/index.test.ts](tests/index.test.ts))
+- `npm run exports` — regenerate every `index.ts` barrel under `src/` (see "Index files" below)
+- `npm run generate` — parse `src/interfaces.ts`, `src/params.ts`, and every query/mutation file via the TypeScript AST to emit `openapi.json`
+- `npm run generate:sdks` — runs OpenAPI Generator over `openapi.json` to produce the typescript-axios SDK in `sdks/typescript/`, then npm-links it
+- `npm run release` — `lint && build` (run before publishing)
+
+CI (`.github/workflows/`) runs `lint` + `tsc` + `build` on pushes to `staging`, regenerates `openapi.json` on PRs from `staging` → `main`, and on push to `main` publishes both `@connectedxm/admin` and the generated `@connectedxm/admin-sdk`. The `staging` → `main` PR is the release path; the `baseBranch` for changesets is `staging`.
+
+## Architecture
+
+### Three core wrappers
+
+Every query/mutation file delegates auth, error handling, and React Query wiring to one of these helpers in [src/queries/](src/queries/) and [src/mutations/](src/mutations/):
+
+- [useConnectedSingleQuery](src/queries/useConnectedSingleQuery.ts) — single GETs. Default `staleTime: 60s`. Translates 401/403/404/460/461 into `onNotAuthorized` / `onModuleForbidden` / `onNotFound` callbacks pulled from `ConnectedXMProvider` and stops retrying for those.
+- [useConnectedInfiniteQuery](src/queries/useConnectedInfiniteQuery.ts) — page-numbered list endpoints. Default `pageSize: 25`. Appends `["SEARCH", search]` to the query key so the cache partitions by search term.
+- [useConnectedCursorQuery](src/queries/useConnectedCursorQuery.ts) — cursor-paginated list endpoints; uses the `cursor` field on `ConnectedXMResponse` for pagination.
+- [useConnectedMutation](src/mutations/useConnectedMutation.ts) — wraps `useMutation`; injects `adminApiParams` and `queryClient` into the mutation function so per-mutation files can invalidate/set query data after a successful response.
+
+All four read auth (`apiUrl`, `organizationId`, `getToken`, `getExecuteAs`) from [ConnectedXMProvider](src/ConnectedXMProvider.tsx) via [useConnectedXM](src/hooks/useConnectedXM.ts) and pass it to the API function as `adminApiParams`. The provider also exposes `onNotAuthorized` / `onModuleForbidden` / `onNotFound` / `onMutationError` callbacks for cross-cutting error handling.
+
+### Conventional file shape
+
+Each query file exports five things in this order: `*_QUERY_KEY`, `SET_*_QUERY_DATA`, the params interface (extending `SingleQueryParams` / `InfiniteQueryParams` / `CursorQueryParams`), the API function, and the hook. Each mutation file exports a params interface (extending `MutationParams`), the API function (which calls `queryClient.invalidateQueries` / setters on success), and the hook. See [useGetAccount.ts](src/queries/accounts/useGetAccount.ts), [useGetAccounts.ts](src/queries/accounts/useGetAccounts.ts), [useCreateAccount.ts](src/mutations/accounts/useCreateAccount.ts), and [useDeleteAccount.ts](src/mutations/accounts/useDeleteAccount.ts) as canonical examples — new files must mirror these exactly so the AST-based OpenAPI generator can pick them up.
+
+The `generate` script's parser ([scripts/generate.ts](scripts/generate.ts)) is strict about this shape: it looks for one exported arrow function (skipping names starting with `use`, `SET_`, or ending in `_QUERY_KEY`) whose first parameter type extends `SingleQueryParams`, `InfiniteQueryParams`, or `MutationParams`, and a return type of `Promise<ConnectedXMResponse<T>>`. Deviations cause the file to be silently dropped from `openapi.json`.
+
+### Where types live
+
+- [src/interfaces.ts](src/interfaces.ts) (~5k lines) — every domain type and enum. Response payload shapes.
+- [src/params.ts](src/params.ts) (~3k lines) — every request body / `*Inputs` shape used as a mutation argument.
+- [ConnectedXMResponse&lt;T&gt;](src/interfaces.ts) — the universal envelope: `{ status, message, data: T, count?, cursor? }`. Every API function returns `Promise<ConnectedXMResponse<...>>`.
+
+The OpenAPI generator parses both files via the TypeScript AST and turns interfaces / type aliases / enums directly into `components.schemas`. It understands `extends`, `Omit<Base, "x">` in heritage clauses, and string-literal unions (which become enum schemas). Type aliases that aren't pure structural types may not round-trip cleanly — prefer interfaces.
+
+### Path aliases
+
+`tsconfig.json` defines `@src/*` → `./src/*` and `@interfaces` → `./src/interfaces`. Files in this repo use both freely. tsup resolves them at build time.
+
+### Index files
+
+Per [.cursor/rules/index-exports.mdc](.cursor/rules/index-exports.mdc): **do not hand-edit `index.ts` files.** Run `npm run exports` after adding or moving a file; the script ([scripts/exports.ts](scripts/exports.ts)) regenerates every barrel under `src/` by walking the directory tree.
+
+### OpenAPI tag hierarchy
+
+[scripts/generate.ts](scripts/generate.ts) derives OpenAPI tags from the file's path under `queries/` or `mutations/` (e.g. `events/passes/useGetEventPasses.ts` → `Events::Passes`). Adding a new top-level resource folder will create a new tag; the script's `tagDescriptions` and `singularToPlural` maps near the bottom of the file may need updating so the tag normalizes and gets a description.
+
+## Conventions when adding endpoints
+
+Cursor rules in [.cursor/rules/](.cursor/rules/) describe the workflow: check [src/params.ts](src/params.ts) and [src/interfaces.ts](src/interfaces.ts) first for existing types; only add new ones if the type doesn't already exist. Then create the file under `src/queries/<resource>/` or `src/mutations/<resource>/` following the canonical example, and run `npm run exports`.

package/dist/index.d.cts

@@ -1657,6 +1657,7 @@ interface Organization extends BaseOrganization {
     maxVideoMins: number | null;
     locales: string[];
     inviteOnly: boolean;
+    autoTranslate: boolean;
     googleTagManagerId: string | null;
     options: object | null;
 }
@@ -6000,6 +6001,7 @@ interface OrganizationUpdateInputs {
     locale?: string | null;
     locales?: string[] | null;
     inviteOnly?: boolean;
+    autoTranslate?: boolean;
     googleTagManagerId?: string | null;
     options?: object | null;
 }

package/dist/index.d.ts

@@ -1657,6 +1657,7 @@ interface Organization extends BaseOrganization {
     maxVideoMins: number | null;
     locales: string[];
     inviteOnly: boolean;
+    autoTranslate: boolean;
     googleTagManagerId: string | null;
     options: object | null;
 }
@@ -6000,6 +6001,7 @@ interface OrganizationUpdateInputs {
     locale?: string | null;
     locales?: string[] | null;
     inviteOnly?: boolean;
+    autoTranslate?: boolean;
     googleTagManagerId?: string | null;
     options?: object | null;
 }

package/openapi.json

@@ -99190,6 +99190,9 @@
               "inviteOnly": {
                 "type": "boolean"
               },
+              "autoTranslate": {
+                "type": "boolean"
+              },
               "googleTagManagerId": {
                 "type": "string",
                 "nullable": true
@@ -99259,6 +99262,7 @@
               "maxVideoMins",
               "locales",
               "inviteOnly",
+              "autoTranslate",
               "googleTagManagerId",
               "options"
             ]
@@ -117559,6 +117563,9 @@
           "inviteOnly": {
             "type": "boolean"
           },
+          "autoTranslate": {
+            "type": "boolean"
+          },
           "googleTagManagerId": {
             "type": "string",
             "nullable": true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@connectedxm/admin",
-  "version": "6.28.2",
+  "version": "6.29.0",
   "description": "Admin API javascript SDK",
   "author": "ConnectedXM Inc.",
   "type": "module",