@sixtyninecommerce/admin 0.1.0

package/README.md

@@ -0,0 +1,147 @@
+# @sixtyninecommerce/admin
+
+The back-office SDK for sixtynine-commerce. Every capability of the platform is a method here —
+no raw GraphQL, no REST paths, no header names.
+
+Built on [`@sixtyninecommerce/core`](https://www.npmjs.com/package/@sixtyninecommerce/core), which
+gives it the tenant context, the error hierarchy, cursor pagination, idempotency keys and retries.
+
+## Install
+
+```bash
+npm install @sixtyninecommerce/admin
+```
+
+## Usage
+
+```ts
+import { createAdminClient } from '@sixtyninecommerce/admin';
+
+const admin = createAdminClient({
+  urls: {
+    vendureUrl: 'https://engine.sixtyninecommerce.com',
+    cmsUrl: 'https://cms.sixtyninecommerce.com',
+    pluginsUrl: 'https://plugins.sixtyninecommerce.com',
+  },
+  auth: { token: process.env.SIXTYNINE_API_TOKEN! },
+  tenant: { scope: { kind: 'channel', code: 'velvet-thread' } },
+});
+
+for await (const form of await admin.content.forms.list()) {
+  console.log(form.slug);
+}
+```
+
+### Credentials
+
+| Principal | How | Where |
+|---|---|---|
+| API token | `auth: { token: 's69t_…' }` | server only — constructing one in a browser throws `CREDENTIAL_IN_BROWSER` |
+| Admin session | `auth: { session: { token?, onToken } }` | server or browser |
+
+A session client can start empty and sign in:
+
+```ts
+const session: { token?: string } = {};
+const admin = createAdminClient({ urls, auth: { session } });
+const me = await admin.auth.login('user@example.com', 'secret');
+const tenant = admin.withTenant({ scope: { kind: 'channel', code: me.channels[0]!.code } });
+```
+
+**The session object you pass IS where the bearer is stored.** Vendure returns a fresh one on a
+response header and the SDK writes it back into `session.token`, so it must be writable — a plain
+property, or a getter with a setter over your own store. A read-only one is refused at construction
+with `SESSION_NOT_WRITABLE` rather than dropping every rotation silently. `onToken` is a
+notification for persisting it across processes, and it fires with `''` when `logout()` ends the
+session so a stored copy can be invalidated.
+
+**In a server, give each request its own session object** — one shared object is one shared
+credential:
+
+```ts
+const admin = createAdminClient({
+  urls,
+  auth: {
+    session: {
+      get token() { return requestContext.token; },
+      set token(next: string | undefined) { requestContext.token = next; },
+    },
+  },
+});
+```
+
+A bearer is not proof of a session: Vendure mints an *anonymous* one for an unauthenticated read.
+Treat "signed in" as "`auth.me()` resolved", never as "a token is stored".
+
+### What an API token cannot do
+
+`apiTokens.*` needs a human session. The engine strips `ManageApiToken` from every token it
+issues, so a token can never manage tokens — including its own — and `platform.*` refuses a token
+in the SDK before the request leaves the process. Mint and revoke credentials from a signed-in
+session:
+
+```ts
+const session: { token?: string } = {};
+const human = createAdminClient({ urls, auth: { session } });
+await human.auth.login('ops@example.com', process.env.OPS_PASSWORD!);
+const scoped = human.withTenant({ scope: { kind: 'channel', code: 'velvet-thread' } });
+
+const created = await scoped.apiTokens.create({
+  name: 'ERP sync',
+  permissions: ['ReadOrder'],
+  expiresAt: '2027-01-01T00:00:00Z',
+});
+console.log(created.token); // shown exactly once
+```
+
+### Knowing what credential you hold
+
+```ts
+const who = await admin.auth.whoami();
+who.kind;          // 'api_token' | 'user'
+who.token?.expiresAt;  // null means it never expires
+who.permissions;   // effective on the ACTIVE channel, not the union
+who.entitlements;  // connected plugin keys for that channel
+```
+
+For a machine credential this is the only way to learn any of it without being refused. It needs a
+tenant — permissions and entitlements have no meaning without a channel — and it is admin-plane
+only: a storefront principal is refused with `PermissionDeniedError`.
+
+### Tenancy
+
+A client with no `tenant.scope` may only call `auth.*` and `channels.byCode()`; every other module
+throws `TENANT_REQUIRED`. An administrator with several channels must say which one they mean — the
+server never guesses. `channels.byCode()` is the exception on purpose: it names the channel in its
+own argument, and it is how you look up the code you are about to scope to. `withTenant()` derives
+a client on another tenant, sharing the principal and the channel cache.
+
+### Writes
+
+Every write takes `{ idempotencyKey?, tenant?, signal? }`. The key is sent as `Idempotency-Key` on a
+REST write and dropped on a GraphQL one — the Admin API has no header for it, so an `apiTokens.*`
+write is never deduplicated.
+
+| Write | Deduplicated? |
+|---|---|
+| `content.forms.upsertBySlug` | yes — the CMS replays the first response for the same key |
+| `seo.redirects.create` | yes — the plugins service does the same |
+| everything else | no; the key is recorded on the wire and acts on nothing |
+
+Where it is honoured, the same key with a **different** body is refused with 409. This SDK never
+retries a write on its own, so a repeat is always one you sent: use a fresh key per intended write
+and reuse it only when retrying that exact write.
+
+### Errors
+
+One hierarchy, all re-exported from this package so you need no direct dependency on
+`@sixtyninecommerce/core`: `ValidationError`, `AuthenticationError`, `PermissionDeniedError`,
+`NotFoundError`, `ConflictError`, `BusinessRuleError`, `RateLimitedError`, `UpstreamError`,
+`TransportError`, and `AdminProjectionError` — this package's own, thrown by `content.forms` when
+the CMS answers a public route with its storefront projection because the credential was not
+accepted for the channel (`ADMIN_PROJECTION_UNAVAILABLE`). All extend `PlatformError`. Branch on
+`error.code`.
+
+## License
+
+MIT

package/dist/api-tokens/index.d.ts

@@ -0,0 +1,29 @@
+import { type Page, type Transport } from '@sixtyninecommerce/core';
+import type { ApiToken, Call, CreateApiTokenInput, ListOptions, UpdateApiTokenInput } from '../types.js';
+export declare const API_TOKEN_FIELDS = "\n  id\n  name\n  tokenPrefix\n  permissions\n  channelId\n  expiresAt\n  lastUsedAt\n  revokedAt\n  createdAt\n";
+export declare const LIST_QUERY = "\n  query ApiTokens($options: ApiTokenListOptions) {\n    apiTokens(options: $options) {\n      totalItems\n      items { \n  id\n  name\n  tokenPrefix\n  permissions\n  channelId\n  expiresAt\n  lastUsedAt\n  revokedAt\n  createdAt\n }\n    }\n  }\n";
+export declare const CREATE_MUTATION = "\n  mutation CreateApiToken($input: CreateApiTokenInput!) {\n    createApiToken(input: $input) {\n      token\n      apiToken { \n  id\n  name\n  tokenPrefix\n  permissions\n  channelId\n  expiresAt\n  lastUsedAt\n  revokedAt\n  createdAt\n }\n    }\n  }\n";
+export declare const UPDATE_MUTATION = "\n  mutation UpdateApiToken($input: UpdateApiTokenInput!) {\n    updateApiToken(input: $input) { \n  id\n  name\n  tokenPrefix\n  permissions\n  channelId\n  expiresAt\n  lastUsedAt\n  revokedAt\n  createdAt\n }\n  }\n";
+export declare const REVOKE_MUTATION = "\n  mutation RevokeApiToken($id: ID!) {\n    revokeApiToken(id: $id) { \n  id\n  name\n  tokenPrefix\n  permissions\n  channelId\n  expiresAt\n  lastUsedAt\n  revokedAt\n  createdAt\n }\n  }\n";
+export declare const DELETE_MUTATION = "\n  mutation DeleteApiTokens($ids: [ID!]!) {\n    deleteApiTokens(ids: $ids) {\n      result\n      message\n    }\n  }\n";
+/** The raw token is shown exactly once, at creation. */
+export interface CreatedApiToken {
+    token: string;
+    apiToken: ApiToken;
+}
+/**
+ * Managing API tokens needs a HUMAN SESSION. The engine strips
+ * `ManageApiToken` from every grant set it issues (`NEVER_GRANTABLE`), so a
+ * token can never manage tokens — including its own — and every method here
+ * answers `PermissionDeniedError FORBIDDEN` for a machine credential. That is
+ * the engine's rule, not the SDK's, so it is documented rather than guarded:
+ * the refusal arrives from the API that owns it.
+ */
+export interface ApiTokensModule {
+    list(options?: ListOptions): Promise<Page<ApiToken>>;
+    create(input: CreateApiTokenInput, options?: Call): Promise<CreatedApiToken>;
+    update(id: string, input: UpdateApiTokenInput, options?: Call): Promise<ApiToken>;
+    revoke(id: string, options?: Call): Promise<ApiToken>;
+    delete(ids: string[], options?: Call): Promise<void>;
+}
+export declare function createApiTokensModule(transport: Transport): ApiTokensModule;

package/dist/api-tokens/index.js

@@ -0,0 +1,90 @@
+import { ConflictError, pageFromVendureList, readOffsetCursor, } from '@sixtyninecommerce/core';
+export const API_TOKEN_FIELDS = /* GraphQL */ `
+  id
+  name
+  tokenPrefix
+  permissions
+  channelId
+  expiresAt
+  lastUsedAt
+  revokedAt
+  createdAt
+`;
+export const LIST_QUERY = /* GraphQL */ `
+  query ApiTokens($options: ApiTokenListOptions) {
+    apiTokens(options: $options) {
+      totalItems
+      items { ${API_TOKEN_FIELDS} }
+    }
+  }
+`;
+export const CREATE_MUTATION = /* GraphQL */ `
+  mutation CreateApiToken($input: CreateApiTokenInput!) {
+    createApiToken(input: $input) {
+      token
+      apiToken { ${API_TOKEN_FIELDS} }
+    }
+  }
+`;
+export const UPDATE_MUTATION = /* GraphQL */ `
+  mutation UpdateApiToken($input: UpdateApiTokenInput!) {
+    updateApiToken(input: $input) { ${API_TOKEN_FIELDS} }
+  }
+`;
+export const REVOKE_MUTATION = /* GraphQL */ `
+  mutation RevokeApiToken($id: ID!) {
+    revokeApiToken(id: $id) { ${API_TOKEN_FIELDS} }
+  }
+`;
+export const DELETE_MUTATION = /* GraphQL */ `
+  mutation DeleteApiTokens($ids: [ID!]!) {
+    deleteApiTokens(ids: $ids) {
+      result
+      message
+    }
+  }
+`;
+const DEFAULT_PAGE_SIZE = 25;
+export function createApiTokensModule(transport) {
+    async function listPage(skip, take, options) {
+        const data = await transport.graphql({ api: 'admin', query: LIST_QUERY, variables: { options: { skip, take } } }, options);
+        return pageFromVendureList(data.apiTokens, skip, take, (cursor) => listPage(readOffsetCursor(cursor), take, options));
+    }
+    return {
+        list(options) {
+            // The Admin API is offset-paged; the offset is hidden inside the cursor so
+            // a consumer only ever sees `Page<T>` (spec §9.3).
+            const take = options?.limit ?? DEFAULT_PAGE_SIZE;
+            const skip = options?.after === undefined ? 0 : readOffsetCursor(options.after);
+            return listPage(skip, take, options);
+        },
+        async create(input, options) {
+            const data = await transport.graphql({ api: 'admin', query: CREATE_MUTATION, variables: { input } }, options);
+            return data.createApiToken;
+        },
+        async update(id, input, options) {
+            const data = await transport.graphql({ api: 'admin', query: UPDATE_MUTATION, variables: { input: { id, ...input } } }, options);
+            return data.updateApiToken;
+        },
+        async revoke(id, options) {
+            const data = await transport.graphql({ api: 'admin', query: REVOKE_MUTATION, variables: { id } }, options);
+            return data.revokeApiToken;
+        },
+        async delete(ids, options) {
+            const data = await transport.graphql({ api: 'admin', query: DELETE_MUTATION, variables: { ids } }, options);
+            // `deleteApiTokens` reports per-id outcomes at HTTP 200 with no error, so
+            // a caller awaiting a void promise would read a refusal as success.
+            const refused = data.deleteApiTokens.filter((entry) => entry.result !== 'DELETED');
+            if (refused.length > 0) {
+                throw new ConflictError({
+                    code: 'API_TOKEN_NOT_DELETED',
+                    message: `${String(refused.length)} of ${String(ids.length)} tokens were not deleted: ${refused
+                        .map((entry) => entry.message ?? 'no reason given')
+                        .join('; ')}`,
+                    status: 409,
+                    service: 'vendure',
+                });
+            }
+        },
+    };
+}

package/dist/auth/index.d.ts

@@ -0,0 +1,61 @@
+import { type Transport } from '@sixtyninecommerce/core';
+import type { Call, Me, WhoAmI } from '../types.js';
+export interface AuthModule {
+    /** Establishes a session. The bearer arrives on a response header, not here. */
+    login(username: string, password: string, options?: Call): Promise<Me>;
+    /**
+     * Ends the session server-side AND clears the bearer, in the caller's own
+     * session object. `onToken` fires with `''` so a persisted copy — a cookie, a
+     * keychain entry, `localStorage` — can be invalidated in the same step.
+     *
+     * Idempotent: with no bearer in hand there is nothing to end, and asking
+     * anyway would make Vendure mint an anonymous session.
+     */
+    logout(options?: Call): Promise<void>;
+    me(options?: Call): Promise<Me>;
+    /**
+     * Describe the credential in hand: its kind, its channels, and — for the
+     * ACTIVE channel — its effective permissions and the plugin entitlements its
+     * tenant has. For a machine credential this is the only way to learn any of
+     * that without being refused; `token.expiresAt` is what an integration checks
+     * against now.
+     *
+     * Unlike the rest of `auth`, it needs a tenant: permissions and entitlements
+     * have no meaning without a channel, and the platform refuses to guess one.
+     * It is also an admin-plane endpoint — a storefront principal is refused with
+     * `PermissionDeniedError`.
+     */
+    whoami(options?: Call): Promise<WhoAmI>;
+}
+/** The session bearer's store, when the client has one (a token client does not). */
+export interface SessionControl {
+    /** Is there a bearer to send at all? */
+    present(): boolean;
+    /** The bearer in force right now — what the next call will send. */
+    current(): string;
+    /** How many rotations this client has STORED, to tell one call's apart. */
+    rotations(): number;
+    /**
+     * Forget it. `sent` makes it conditional: clear only while the slot still
+     * holds that bearer, so a late response proving one credential dead cannot
+     * sign out the session that replaced it.
+     */
+    end(sent?: string): void;
+}
+/**
+ * `session` is present only for a session principal. It exists for two reasons.
+ *
+ * `logout()` has to clear the bearer — Vendure signals sign-out with an EMPTY
+ * `vendure-auth-token` header, which the transport correctly refuses to treat
+ * as a rotation, so nothing else ever would.
+ *
+ * And `me()`/`logout()` must not go out at all without one. `me` is
+ * `@Allow(Authenticated, Owner)`, and for an Owner-allowed operation Vendure
+ * MINTS AN ANONYMOUS SESSION for an unauthenticated request and returns its
+ * token on `vendure-auth-token`. The SDK would store that as if it were a
+ * credential, so a dashboard that signed out and re-checked `me()` would have a
+ * bearer again — and an app gating its shell on "is a token stored?" would show
+ * itself as signed in. Refusing before the wire is also the honest answer: with
+ * no bearer there is no session to report on.
+ */
+export declare function createAuthModule(transport: Transport, session?: SessionControl): AuthModule;

package/dist/auth/index.js

@@ -0,0 +1,162 @@
+import { AuthenticationError, errorFromErrorResult, isErrorResult, PermissionDeniedError, UNSCOPED_TENANT, } from '@sixtyninecommerce/core';
+import { LOGIN_MUTATION, LOGOUT_MUTATION, ME_QUERY } from './queries.js';
+/**
+ * `me` is nullable on the Admin API: an unauthenticated request is answered
+ * with `null`, not with an error. Returning that as a `Me` would hand the
+ * caller `undefined` under a `string` type, so it is turned into the
+ * authentication failure it actually is.
+ */
+/**
+ * A bearer the Admin API does not accept makes `me` answer `FORBIDDEN`, which
+ * reads as PermissionDeniedError — "you may not do this" — when the truth is
+ * "your session is over". That sends a dashboard to an error page instead of to
+ * its sign-in screen, so it is narrowed for `me` ONLY; everywhere else
+ * FORBIDDEN keeps its meaning.
+ *
+ * Verified against the installed engine rather than assumed: `me` is
+ * `@Allow(Permission.Authenticated, Permission.Owner)`, and because `Owner` is
+ * in that list the guard never refuses it — every FORBIDDEN comes from
+ * `BaseAuthResolver.me`, which throws when there is no active user AND when an
+ * authenticated user has no Administrator row. The second is a real
+ * authorization refusal, but it is unreachable through this SDK: `login()`
+ * refuses a non-administrator on the Admin API in the first place. So the
+ * narrowing is safe for every session this client can hold, and `cause` keeps
+ * the original for the case that is not.
+ */
+function asAuthFailure(error) {
+    if (!(error instanceof PermissionDeniedError))
+        return error;
+    return new AuthenticationError({
+        code: 'NOT_AUTHENTICATED',
+        message: 'No active session. Call auth.login() first, or supply an API token.',
+        status: 401,
+        service: 'vendure',
+        ...(error.traceId ? { traceId: error.traceId } : {}),
+        cause: error,
+    });
+}
+function readMe(data) {
+    const me = data.me;
+    if (!me) {
+        // Built directly rather than run through `errorFromErrorResult`: Vendure
+        // sent no ErrorResult, it sent `null`. Synthesising one would land on the
+        // default branch and classify a missing session as a business rule.
+        throw new AuthenticationError({
+            code: 'NOT_AUTHENTICATED',
+            message: 'No active session. Call auth.login() first, or supply an API token.',
+            status: 401,
+            service: 'vendure',
+        });
+    }
+    return {
+        id: me.id,
+        identifier: me.identifier,
+        channels: me.channels,
+        administrator: data.activeAdministrator,
+    };
+}
+/**
+ * `session` is present only for a session principal. It exists for two reasons.
+ *
+ * `logout()` has to clear the bearer — Vendure signals sign-out with an EMPTY
+ * `vendure-auth-token` header, which the transport correctly refuses to treat
+ * as a rotation, so nothing else ever would.
+ *
+ * And `me()`/`logout()` must not go out at all without one. `me` is
+ * `@Allow(Authenticated, Owner)`, and for an Owner-allowed operation Vendure
+ * MINTS AN ANONYMOUS SESSION for an unauthenticated request and returns its
+ * token on `vendure-auth-token`. The SDK would store that as if it were a
+ * credential, so a dashboard that signed out and re-checked `me()` would have a
+ * bearer again — and an app gating its shell on "is a token stored?" would show
+ * itself as signed in. Refusing before the wire is also the honest answer: with
+ * no bearer there is no session to report on.
+ */
+export function createAuthModule(transport, session) {
+    const notAuthenticated = () => new AuthenticationError({
+        code: 'NOT_AUTHENTICATED',
+        message: 'No active session. Call auth.login() first, or supply an API token.',
+        status: 401,
+        service: 'vendure',
+    });
+    /**
+     * Auth documents go out UNSCOPED, even on a tenant-scoped client: a session
+     * belongs to the user, not to a tenant, and `login` happens before the caller
+     * knows which channels it may address. Sending a channel token there would
+     * also make a client that has no tenant yet unable to sign in at all.
+     */
+    const unscoped = (options) => ({
+        ...options,
+        tenant: UNSCOPED_TENANT,
+        allowUnscoped: true,
+    });
+    async function me(options) {
+        if (session && !session.present())
+            throw notAuthenticated();
+        const sent = session?.current();
+        try {
+            const data = await transport.graphql({ api: 'admin', query: ME_QUERY }, unscoped(options));
+            return readMe(data);
+        }
+        catch (error) {
+            const failure = asAuthFailure(error);
+            // A bearer the engine refused is dead, and `me` is Owner-allowed — so
+            // Vendure answered this very request by MINTING an anonymous session and
+            // returning its token, which the client has just stored as if it were a
+            // credential. Drop it, or `present()` reports a session the user never
+            // obtained and an app gating on "is a token stored?" stays signed in.
+            if (failure instanceof AuthenticationError)
+                session?.end(sent);
+            throw failure;
+        }
+    }
+    return {
+        async login(username, password, options) {
+            const rotationsBefore = session?.rotations();
+            const data = await transport.graphql({ api: 'admin', query: LOGIN_MUTATION, variables: { username, password } }, unscoped(options));
+            // Vendure answers a bad password with HTTP 200 and an ErrorResult member.
+            if (isErrorResult(data.login))
+                throw errorFromErrorResult(data.login);
+            // The session bearer arrives on the `vendure-auth-token` response header.
+            // If none did, the credentials were right and the client still has no way
+            // to authenticate anything — say that, rather than let the `me()` below
+            // report it as "no active session" after a successful sign-in.
+            //
+            // Asked as "did THIS sign-in store a bearer", never as "is some bearer
+            // present": a client that already held one — an account switch, or a
+            // token restored from a keychain — would otherwise skip the check, keep
+            // the OLD bearer, and resolve `login()` as the administrator who was
+            // already signed in. Vendure does not invalidate their session, so every
+            // later call would act as them, audit trail included.
+            if (session && session.rotations() === rotationsBefore) {
+                throw new AuthenticationError({
+                    code: 'NO_SESSION_BEARER',
+                    message: 'The engine accepted the credentials but returned no vendure-auth-token header, so this client has no bearer to send. The Admin API must be configured with the `bearer` token method.',
+                    status: 401,
+                    service: 'vendure',
+                });
+            }
+            return me(options);
+        },
+        async logout(options) {
+            // Idempotent, and it must not go out unauthenticated: Vendure would mint
+            // an anonymous session and hand back its token, arming the client again.
+            if (session && !session.present())
+                return;
+            await transport.graphql({ api: 'admin', query: LOGOUT_MUTATION }, unscoped(options));
+            // Only after the server confirms: clearing on a failed logout would tell
+            // the caller they are signed out while the session is still live.
+            session?.end();
+        },
+        // `async` so the guard REJECTS rather than throwing synchronously: every
+        // other method on this client returns a rejected promise, and a caller who
+        // only attached `.catch()` would otherwise get an uncatchable throw.
+        async whoami(options) {
+            if (session && !session.present())
+                throw notAuthenticated();
+            // Scoped on purpose: `x-channel-id` is what selects the active channel,
+            // and the service refuses a multi-channel principal that names none.
+            return transport.rest('plugins', { method: 'GET', path: '/me' }, options);
+        },
+        me,
+    };
+}

package/dist/auth/queries.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The Admin API documents this SDK's auth uses.
+ *
+ * `LOGIN` is sent WITHOUT a channel token: a session belongs to the user, not
+ * to a tenant, and the channels the user may address come back from `ME`.
+ * Vendure returns the session bearer on the `vendure-auth-token` RESPONSE
+ * header, which the transport hands to `Principal.onToken`.
+ */
+export declare const LOGIN_MUTATION = "\n  mutation Login($username: String!, $password: String!) {\n    login(username: $username, password: $password) {\n      __typename\n      ... on CurrentUser {\n        id\n      }\n      ... on ErrorResult {\n        errorCode\n        message\n      }\n    }\n  }\n";
+export declare const ME_QUERY = "\n  query Me {\n    me {\n      id\n      identifier\n      channels {\n        id\n        code\n        token\n        permissions\n      }\n    }\n    activeAdministrator {\n      id\n      firstName\n      lastName\n      emailAddress\n    }\n  }\n";
+export declare const LOGOUT_MUTATION = "\n  mutation Logout {\n    logout {\n      success\n    }\n  }\n";

package/dist/auth/queries.js

@@ -0,0 +1,49 @@
+/**
+ * The Admin API documents this SDK's auth uses.
+ *
+ * `LOGIN` is sent WITHOUT a channel token: a session belongs to the user, not
+ * to a tenant, and the channels the user may address come back from `ME`.
+ * Vendure returns the session bearer on the `vendure-auth-token` RESPONSE
+ * header, which the transport hands to `Principal.onToken`.
+ */
+export const LOGIN_MUTATION = /* GraphQL */ `
+  mutation Login($username: String!, $password: String!) {
+    login(username: $username, password: $password) {
+      __typename
+      ... on CurrentUser {
+        id
+      }
+      ... on ErrorResult {
+        errorCode
+        message
+      }
+    }
+  }
+`;
+export const ME_QUERY = /* GraphQL */ `
+  query Me {
+    me {
+      id
+      identifier
+      channels {
+        id
+        code
+        token
+        permissions
+      }
+    }
+    activeAdministrator {
+      id
+      firstName
+      lastName
+      emailAddress
+    }
+  }
+`;
+export const LOGOUT_MUTATION = /* GraphQL */ `
+  mutation Logout {
+    logout {
+      success
+    }
+  }
+`;

package/dist/client.d.ts

@@ -0,0 +1,83 @@
+import { type DeprecationNotice, type RateLimitInfo, type RetryPolicy, type TenantContext, type TenantScope } from '@sixtyninecommerce/core';
+import { type ApiTokensModule } from './api-tokens/index.js';
+import { type AuthModule } from './auth/index.js';
+import { type FormsModule } from './content/forms.js';
+import { type RedirectsModule } from './seo/redirects.js';
+import { type ChannelsModule } from './tenant/channels.js';
+export interface AdminClientConfig {
+    urls: {
+        vendureUrl: string;
+        cmsUrl: string;
+        pluginsUrl: string;
+    };
+    /**
+     * A machine credential (`token`) or a human session.
+     *
+     * A session may start empty: the client holds the bearer `login()` obtains,
+     * so nothing has to be stored to use it. It never writes back into this
+     * object — `onToken` is the only way a caller learns the bearer, and it is
+     * what to persist across processes.
+     *
+     * `token` is read LIVE on every call, so a getter over the caller's own
+     * store works: whenever that value changes it becomes the bearer, which is
+     * how a per-request credential, a token restored after construction, and a
+     * sign-out that clears it all take effect.
+     */
+    auth: {
+        token: string;
+    } | {
+        session: SessionConfig;
+    };
+    tenant?: Partial<TenantContext> & {
+        scope?: TenantScope;
+    };
+    fetch?: typeof globalThis.fetch;
+    retry?: Partial<RetryPolicy>;
+    timeoutMs?: number;
+    onDeprecation?: (notice: DeprecationNotice) => void;
+}
+export interface AdminClient {
+    auth: AuthModule;
+    apiTokens: ApiTokensModule;
+    channels: ChannelsModule;
+    content: {
+        forms: FormsModule;
+    };
+    seo: {
+        redirects: RedirectsModule;
+    };
+    /** Human SuperAdmin surface. Empty in phase 0. */
+    platform: Record<string, never>;
+    /** A derived client on another tenant, sharing this one's principal. */
+    withTenant(tenant: Partial<TenantContext> & {
+        scope?: TenantScope;
+    }): AdminClient;
+    readonly rateLimit: RateLimitInfo | null;
+}
+export interface SessionConfig {
+    /**
+     * The session bearer, and where this client STORES it. Vendure returns a
+     * fresh one on a response header, and the SDK writes it back here — so this
+     * object, not a hidden slot inside the client, is the single source of truth.
+     * It must be writable (a plain property, or a getter WITH a setter over your
+     * own store); `createAdminClient` refuses a read-only one rather than
+     * silently dropping every rotation.
+     *
+     * **In a server, give each request its own session object** (or a
+     * getter/setter pair over your request context). One shared object is one
+     * shared credential: the bearer the last sign-in produced is the bearer the
+     * next request sends.
+     */
+    token?: string;
+    /**
+     * Called with every bearer this client stores, for persisting it across
+     * processes — and with `''` when `logout()` ends the session, so a stored
+     * copy can be invalidated.
+     *
+     * A bearer is not proof of a session: Vendure mints an ANONYMOUS session for
+     * an unauthenticated read. Treat "signed in" as "`auth.me()` resolved", never
+     * as "a token is stored".
+     */
+    onToken?: (token: string) => void;
+}
+export declare function createAdminClient(config: AdminClientConfig): AdminClient;