@crowdedkingdoms/crowdyjs 1.0.0

package/dist/domains/actors.d.ts

@@ -0,0 +1,117 @@
+import type { GraphQLClient } from '../client.js';
+import { type ActorQuery, type ActorQueryVariables, type ActorsQuery, type ActorsQueryVariables, type ActorsConnectionQuery, type ActorsConnectionQueryVariables, type BatchLookupActorsQuery, type BatchLookupActorsQueryVariables, type CreateActorMutation, type CreateActorMutationVariables, type UpdateActorMutation, type UpdateActorMutationVariables, type DeleteActorMutation, type DeleteActorMutationVariables, type UpdateActorStateMutation, type UpdateActorStateMutationVariables } from '../generated/graphql.js';
+/**
+ * Persisted-actor (player / NPC) CRUD and filtering on the **game-api**.
+ * Exposed as `client.actors`.
+ *
+ * An "actor" here is the durable, server-stored record of a participant
+ * (identity, owning app, optional avatar, last-known chunk, and a state blob) —
+ * not the high-frequency spatial replication stream. For real-time position
+ * and state fan-out use the UDP path instead (`client.udp.sendActorUpdate(...)`
+ * or the ergonomic `client.world(appId).actor()` helper), which is unchanged
+ * and far cheaper per update.
+ *
+ * Actor ids are exactly **32 ASCII characters** (the UDP-wire actor id), **not**
+ * a hyphenated RFC-4122 UUID. Use {@link generateCrowdyUuid} to mint one.
+ * `BigInt` values (`appId`, `avatarId`, `userId`) are sent and received as
+ * decimal strings.
+ *
+ * Every method requires an authenticated session (a Bearer token set via
+ * `client.auth.login()` or `client.setToken()`) and that the caller is
+ * entitled to the target app, or it throws {@link CrowdyGraphQLError}
+ * (`UNAUTHENTICATED` / `FORBIDDEN`).
+ */
+export declare class ActorsAPI {
+    private gql;
+    constructor(gql: GraphQLClient);
+    /**
+     * Fetch a single persisted actor by its 32-character actor id.
+     *
+     * @param uuid - The actor's 32-ASCII-character id.
+     * @returns The {@link Actor}, or `null` if no actor with that id exists.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN` if the caller
+     *   isn't entitled to the actor's app.
+     */
+    get(uuid: ActorQueryVariables['uuid']): Promise<ActorQuery['actor']>;
+    /**
+     * List persisted actors, optionally narrowed by an {@link ActorFilterInput}
+     * (e.g. by app, owning user, or avatar). Omit the filter to use its defaults.
+     *
+     * @param filter - Optional filter; fields are ANDed together.
+     * @returns The matching actors.
+     * @throws {CrowdyGraphQLError} on auth/validation failures.
+     */
+    list(filter?: ActorsQueryVariables['filter']): Promise<ActorsQuery['actors']>;
+    /**
+     * Relay-style cursor pagination over the caller's actors — the preferred
+     * alternative to {@link list} for large result sets. Page with `first` plus
+     * the previous page's `pageInfo.endCursor` as `after`; `filter` fields are
+     * ANDed together. See https://docs.crowdedkingdoms.com/overview/pagination.
+     *
+     * @param args - Optional `first` (default 50, max 200), `after` cursor, and
+     *   {@link ActorFilterInput}.
+     * @returns An {@link ActorsConnection} (`edges { cursor node }`, `pageInfo`,
+     *   `totalCount`).
+     */
+    listConnection(args?: ActorsConnectionQueryVariables): Promise<ActorsConnectionQuery['actorsConnection']>;
+    /**
+     * Resolve many actors in one round-trip by id (and/or the other keys the
+     * {@link BatchActorLookupInput} accepts). Prefer this over calling
+     * {@link get} in a loop — it avoids N requests and N auth checks.
+     *
+     * @param input - The batch lookup keys.
+     * @returns The actors that were found (missing ids are simply omitted).
+     */
+    batchLookup(input: BatchLookupActorsQueryVariables['input']): Promise<BatchLookupActorsQuery['batchLookupActors']>;
+    /**
+     * Create a persisted actor. `input.uuid` must be a unique 32-ASCII-character
+     * id and `input.appId` the owning app; `chunk` is the initial grid position.
+     * `avatarId`, `privateState`, and `publicState` are optional (state blobs are
+     * base64-encoded binary).
+     *
+     * @param input - {@link CreateActorInput}.
+     * @returns The newly created {@link Actor}.
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` (e.g. malformed/duplicate
+     *   uuid), `FORBIDDEN` if not entitled to the app, or `UNAUTHENTICATED`.
+     */
+    create(input: CreateActorMutationVariables['input']): Promise<CreateActorMutation['createActor']>;
+    /**
+     * Patch an existing actor. Only the fields present on `input` change; omitted
+     * fields are left untouched.
+     *
+     * @param uuid - The actor's 32-character id.
+     * @param input - Fields to change ({@link UpdateActorInput}).
+     * @returns The updated {@link Actor}.
+     * @throws {CrowdyGraphQLError} if the actor doesn't exist or the caller lacks
+     *   access.
+     */
+    update(uuid: UpdateActorMutationVariables['uuid'], input: UpdateActorMutationVariables['input']): Promise<UpdateActorMutation['updateActor']>;
+    /**
+     * Delete a persisted actor.
+     *
+     * Pass an `idempotencyKey` to make retries safe: replaying with the same key
+     * returns the first result instead of re-applying, while the same key with a
+     * **different** `uuid` throws {@link CrowdyGraphQLError} with
+     * `code === 'IDEMPOTENCY_CONFLICT'`. Keys expire server-side after 24h.
+     * Requires game-api ≥ v0.10.3.
+     *
+     * @param uuid - The actor's 32-character id.
+     * @param idempotencyKey - Optional client-supplied key for safe retries.
+     * @returns The deleted {@link Actor} (its identifying fields).
+     * @throws {CrowdyGraphQLError} `IDEMPOTENCY_CONFLICT`, `FORBIDDEN`, or
+     *   `UNAUTHENTICATED`.
+     */
+    delete(uuid: DeleteActorMutationVariables['uuid'], idempotencyKey?: DeleteActorMutationVariables['idempotencyKey']): Promise<DeleteActorMutation['deleteActor']>;
+    /**
+     * Replace just an actor's state blob(s) without touching its other fields —
+     * a lighter write than {@link update} when only `privateState`/`publicState`
+     * change. State is base64-encoded binary.
+     *
+     * @param uuid - The actor's 32-character id.
+     * @param input - {@link UpdateActorStateInput}.
+     * @returns The updated {@link Actor}.
+     * @throws {CrowdyGraphQLError} on auth/validation failures.
+     */
+    updateState(uuid: UpdateActorStateMutationVariables['uuid'], input: UpdateActorStateMutationVariables['input']): Promise<UpdateActorStateMutation['updateActorState']>;
+}
+//# sourceMappingURL=actors.d.ts.map

package/dist/domains/actors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actors.d.ts","sourceRoot":"","sources":["../../src/domains/actors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,mBAAmB,EAExB,KAAK,WAAW,EAChB,KAAK,oBAAoB,EAEzB,KAAK,qBAAqB,EAC1B,KAAK,8BAA8B,EAEnC,KAAK,sBAAsB,EAC3B,KAAK,+BAA+B,EAEpC,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,EAEjC,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,EAEjC,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,EAEjC,KAAK,wBAAwB,EAC7B,KAAK,iCAAiC,EACvC,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,SAAS;IACR,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAEtC;;;;;;;OAOG;IACG,GAAG,CAAC,IAAI,EAAE,mBAAmB,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAK1E;;;;;;;OAOG;IACG,IAAI,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAKnF;;;;;;;;;;OAUG;IACG,cAAc,CAClB,IAAI,GAAE,8BAAmC,GACxC,OAAO,CAAC,qBAAqB,CAAC,kBAAkB,CAAC,CAAC;IAKrD;;;;;;;OAOG;IACG,WAAW,CACf,KAAK,EAAE,+BAA+B,CAAC,OAAO,CAAC,GAC9C,OAAO,CAAC,sBAAsB,CAAC,mBAAmB,CAAC,CAAC;IAKvD;;;;;;;;;;OAUG;IACG,MAAM,CACV,KAAK,EAAE,4BAA4B,CAAC,OAAO,CAAC,GAC3C,OAAO,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC;IAK9C;;;;;;;;;OASG;IACG,MAAM,CACV,IAAI,EAAE,4BAA4B,CAAC,MAAM,CAAC,EAC1C,KAAK,EAAE,4BAA4B,CAAC,OAAO,CAAC,GAC3C,OAAO,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC;IAK9C;;;;;;;;;;;;;;OAcG;IACG,MAAM,CACV,IAAI,EAAE,4BAA4B,CAAC,MAAM,CAAC,EAC1C,cAAc,CAAC,EAAE,4BAA4B,CAAC,gBAAgB,CAAC,GAC9D,OAAO,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC;IAK9C;;;;;;;;;OASG;IACG,WAAW,CACf,IAAI,EAAE,iCAAiC,CAAC,MAAM,CAAC,EAC/C,KAAK,EAAE,iCAAiC,CAAC,OAAO,CAAC,GAChD,OAAO,CAAC,wBAAwB,CAAC,kBAAkB,CAAC,CAAC;CAIzD"}

package/dist/domains/actors.js

@@ -0,0 +1,140 @@
+import { ActorDocument, ActorsDocument, ActorsConnectionDocument, BatchLookupActorsDocument, CreateActorDocument, UpdateActorDocument, DeleteActorDocument, UpdateActorStateDocument, } from '../generated/graphql.js';
+/**
+ * Persisted-actor (player / NPC) CRUD and filtering on the **game-api**.
+ * Exposed as `client.actors`.
+ *
+ * An "actor" here is the durable, server-stored record of a participant
+ * (identity, owning app, optional avatar, last-known chunk, and a state blob) —
+ * not the high-frequency spatial replication stream. For real-time position
+ * and state fan-out use the UDP path instead (`client.udp.sendActorUpdate(...)`
+ * or the ergonomic `client.world(appId).actor()` helper), which is unchanged
+ * and far cheaper per update.
+ *
+ * Actor ids are exactly **32 ASCII characters** (the UDP-wire actor id), **not**
+ * a hyphenated RFC-4122 UUID. Use {@link generateCrowdyUuid} to mint one.
+ * `BigInt` values (`appId`, `avatarId`, `userId`) are sent and received as
+ * decimal strings.
+ *
+ * Every method requires an authenticated session (a Bearer token set via
+ * `client.auth.login()` or `client.setToken()`) and that the caller is
+ * entitled to the target app, or it throws {@link CrowdyGraphQLError}
+ * (`UNAUTHENTICATED` / `FORBIDDEN`).
+ */
+export class ActorsAPI {
+    constructor(gql) {
+        this.gql = gql;
+    }
+    /**
+     * Fetch a single persisted actor by its 32-character actor id.
+     *
+     * @param uuid - The actor's 32-ASCII-character id.
+     * @returns The {@link Actor}, or `null` if no actor with that id exists.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN` if the caller
+     *   isn't entitled to the actor's app.
+     */
+    async get(uuid) {
+        const data = await this.gql.request(ActorDocument, { uuid });
+        return data.actor;
+    }
+    /**
+     * List persisted actors, optionally narrowed by an {@link ActorFilterInput}
+     * (e.g. by app, owning user, or avatar). Omit the filter to use its defaults.
+     *
+     * @param filter - Optional filter; fields are ANDed together.
+     * @returns The matching actors.
+     * @throws {CrowdyGraphQLError} on auth/validation failures.
+     */
+    async list(filter) {
+        const data = await this.gql.request(ActorsDocument, { filter });
+        return data.actors;
+    }
+    /**
+     * Relay-style cursor pagination over the caller's actors — the preferred
+     * alternative to {@link list} for large result sets. Page with `first` plus
+     * the previous page's `pageInfo.endCursor` as `after`; `filter` fields are
+     * ANDed together. See https://docs.crowdedkingdoms.com/overview/pagination.
+     *
+     * @param args - Optional `first` (default 50, max 200), `after` cursor, and
+     *   {@link ActorFilterInput}.
+     * @returns An {@link ActorsConnection} (`edges { cursor node }`, `pageInfo`,
+     *   `totalCount`).
+     */
+    async listConnection(args = {}) {
+        const data = await this.gql.request(ActorsConnectionDocument, args);
+        return data.actorsConnection;
+    }
+    /**
+     * Resolve many actors in one round-trip by id (and/or the other keys the
+     * {@link BatchActorLookupInput} accepts). Prefer this over calling
+     * {@link get} in a loop — it avoids N requests and N auth checks.
+     *
+     * @param input - The batch lookup keys.
+     * @returns The actors that were found (missing ids are simply omitted).
+     */
+    async batchLookup(input) {
+        const data = await this.gql.request(BatchLookupActorsDocument, { input });
+        return data.batchLookupActors;
+    }
+    /**
+     * Create a persisted actor. `input.uuid` must be a unique 32-ASCII-character
+     * id and `input.appId` the owning app; `chunk` is the initial grid position.
+     * `avatarId`, `privateState`, and `publicState` are optional (state blobs are
+     * base64-encoded binary).
+     *
+     * @param input - {@link CreateActorInput}.
+     * @returns The newly created {@link Actor}.
+     * @throws {CrowdyGraphQLError} `BAD_USER_INPUT` (e.g. malformed/duplicate
+     *   uuid), `FORBIDDEN` if not entitled to the app, or `UNAUTHENTICATED`.
+     */
+    async create(input) {
+        const data = await this.gql.request(CreateActorDocument, { input });
+        return data.createActor;
+    }
+    /**
+     * Patch an existing actor. Only the fields present on `input` change; omitted
+     * fields are left untouched.
+     *
+     * @param uuid - The actor's 32-character id.
+     * @param input - Fields to change ({@link UpdateActorInput}).
+     * @returns The updated {@link Actor}.
+     * @throws {CrowdyGraphQLError} if the actor doesn't exist or the caller lacks
+     *   access.
+     */
+    async update(uuid, input) {
+        const data = await this.gql.request(UpdateActorDocument, { uuid, input });
+        return data.updateActor;
+    }
+    /**
+     * Delete a persisted actor.
+     *
+     * Pass an `idempotencyKey` to make retries safe: replaying with the same key
+     * returns the first result instead of re-applying, while the same key with a
+     * **different** `uuid` throws {@link CrowdyGraphQLError} with
+     * `code === 'IDEMPOTENCY_CONFLICT'`. Keys expire server-side after 24h.
+     * Requires game-api ≥ v0.10.3.
+     *
+     * @param uuid - The actor's 32-character id.
+     * @param idempotencyKey - Optional client-supplied key for safe retries.
+     * @returns The deleted {@link Actor} (its identifying fields).
+     * @throws {CrowdyGraphQLError} `IDEMPOTENCY_CONFLICT`, `FORBIDDEN`, or
+     *   `UNAUTHENTICATED`.
+     */
+    async delete(uuid, idempotencyKey) {
+        const data = await this.gql.request(DeleteActorDocument, { uuid, idempotencyKey });
+        return data.deleteActor;
+    }
+    /**
+     * Replace just an actor's state blob(s) without touching its other fields —
+     * a lighter write than {@link update} when only `privateState`/`publicState`
+     * change. State is base64-encoded binary.
+     *
+     * @param uuid - The actor's 32-character id.
+     * @param input - {@link UpdateActorStateInput}.
+     * @returns The updated {@link Actor}.
+     * @throws {CrowdyGraphQLError} on auth/validation failures.
+     */
+    async updateState(uuid, input) {
+        const data = await this.gql.request(UpdateActorStateDocument, { uuid, input });
+        return data.updateActorState;
+    }
+}

package/dist/domains/admin.d.ts

@@ -0,0 +1,61 @@
+import type { OrganizationsAPI } from './organizations.js';
+import type { AppAccessAPI } from './appAccess.js';
+import type { BillingAPI } from './billing.js';
+import type { PaymentsAPI } from './payments.js';
+import type { QuotasAPI } from './quotas.js';
+import type { EnvironmentsAPI } from './environments.js';
+import type { UsageAPI } from './usage.js';
+import type { SharedEnvironmentAPI } from './sharedEnvironment.js';
+import type { GameAppsAPI } from './gameApps.js';
+/**
+ * Studio-admin facade — exposed as `client.admin`.
+ *
+ * Groups the privileged studio-administration sub-clients under one namespace so
+ * the browser-first, end-user surface (`client.auth`, `client.udp`,
+ * `client.world(...)`, ...) stays visually distinct from the management/admin
+ * surface a studio backend drives with a privileged token. These are the same
+ * instances also reachable at the top level (e.g. `client.billing`), grouped
+ * here for discoverability.
+ *
+ * Operator-only platform operations live separately under `client.operator`
+ * (requires `is_operator`).
+ *
+ * @example
+ * ```ts
+ * const org = await client.admin.organizations.create({ name, slug });
+ * const tier = await client.admin.appAccess.createTier({ ... });
+ * await client.admin.billing.setAppBudget(orgId, appId, '5000');
+ * ```
+ */
+export declare class AdminAPI {
+    /** Organizations, members, RBAC roles, and org API tokens. */
+    readonly organizations: OrganizationsAPI;
+    /** App access tiers + per-user access grants. */
+    readonly appAccess: AppAccessAPI;
+    /** Org wallet + per-app spend budgets. */
+    readonly billing: BillingAPI;
+    /** Payment checkouts (wallet top-ups, plan purchases). */
+    readonly payments: PaymentsAPI;
+    /** Usage quotas at the org/app scope. */
+    readonly quotas: QuotasAPI;
+    /** Dedicated customer environments: provision, scale, deploy. */
+    readonly environments: EnvironmentsAPI;
+    /** Replication + GraphQL usage reporting. */
+    readonly usage: UsageAPI;
+    /** Shared-environment publishing, runtime gating, auto-billing. */
+    readonly sharedEnvironment: SharedEnvironmentAPI;
+    /** App grids + grid runtime-permission administration. */
+    readonly grids: GameAppsAPI;
+    constructor(deps: {
+        organizations: OrganizationsAPI;
+        appAccess: AppAccessAPI;
+        billing: BillingAPI;
+        payments: PaymentsAPI;
+        quotas: QuotasAPI;
+        environments: EnvironmentsAPI;
+        usage: UsageAPI;
+        sharedEnvironment: SharedEnvironmentAPI;
+        grids: GameAppsAPI;
+    });
+}
+//# sourceMappingURL=admin.d.ts.map

package/dist/domains/admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../../src/domains/admin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AACnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,QAAQ;IACnB,8DAA8D;IAC9D,QAAQ,CAAC,aAAa,EAAE,gBAAgB,CAAC;IACzC,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,YAAY,CAAC;IACjC,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,eAAe,CAAC;IACvC,6CAA6C;IAC7C,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;IACzB,mEAAmE;IACnE,QAAQ,CAAC,iBAAiB,EAAE,oBAAoB,CAAC;IACjD,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;gBAEhB,IAAI,EAAE;QAChB,aAAa,EAAE,gBAAgB,CAAC;QAChC,SAAS,EAAE,YAAY,CAAC;QACxB,OAAO,EAAE,UAAU,CAAC;QACpB,QAAQ,EAAE,WAAW,CAAC;QACtB,MAAM,EAAE,SAAS,CAAC;QAClB,YAAY,EAAE,eAAe,CAAC;QAC9B,KAAK,EAAE,QAAQ,CAAC;QAChB,iBAAiB,EAAE,oBAAoB,CAAC;QACxC,KAAK,EAAE,WAAW,CAAC;KACpB;CAWF"}

package/dist/domains/admin.js

@@ -0,0 +1,33 @@
+/**
+ * Studio-admin facade — exposed as `client.admin`.
+ *
+ * Groups the privileged studio-administration sub-clients under one namespace so
+ * the browser-first, end-user surface (`client.auth`, `client.udp`,
+ * `client.world(...)`, ...) stays visually distinct from the management/admin
+ * surface a studio backend drives with a privileged token. These are the same
+ * instances also reachable at the top level (e.g. `client.billing`), grouped
+ * here for discoverability.
+ *
+ * Operator-only platform operations live separately under `client.operator`
+ * (requires `is_operator`).
+ *
+ * @example
+ * ```ts
+ * const org = await client.admin.organizations.create({ name, slug });
+ * const tier = await client.admin.appAccess.createTier({ ... });
+ * await client.admin.billing.setAppBudget(orgId, appId, '5000');
+ * ```
+ */
+export class AdminAPI {
+    constructor(deps) {
+        this.organizations = deps.organizations;
+        this.appAccess = deps.appAccess;
+        this.billing = deps.billing;
+        this.payments = deps.payments;
+        this.quotas = deps.quotas;
+        this.environments = deps.environments;
+        this.usage = deps.usage;
+        this.sharedEnvironment = deps.sharedEnvironment;
+        this.grids = deps.grids;
+    }
+}

package/dist/domains/appAccess.d.ts

@@ -0,0 +1,141 @@
+import type { GraphQLClient } from '../client.js';
+import { type AppAccessTiersQuery, type MyAppAccessQuery, type AppUserAccessByAppQuery, type AppUserAccessConnectionQuery, type AppUserAccessConnectionQueryVariables, type RuntimePermissionsQuery, type AppGrantMemberCandidatesQuery, type ClaimFreeAppAccessMutation, type GrantMyAppAccessMutation, type CreateAccessTierMutation, type UpdateAccessTierMutation, type ArchiveAccessTierMutation, type GrantAppAccessMutation, type RevokeAppAccessMutation, type CreateAccessTierInput, type UpdateAccessTierInput, type GrantAppAccessInput } from '../generated/graphql.js';
+/**
+ * App access tiers + per-user access grants — exposed as `client.appAccess`
+ * (and grouped under `client.admin`).
+ *
+ * Targets the **management-api**. Tiers define the runtime-permission bundles
+ * (`access`, `teleport`, `update_voxel_data`, `use_voice_chat`, ...) a player
+ * gets; grants attach a user to a tier. New apps auto-provision an open default
+ * tier, so most players need no explicit grant.
+ *
+ * Reads of the tier catalog ({@link tiers}) are public; {@link myAccess} needs
+ * a session; tier admin and grant/revoke require the `manage_access_tiers` app
+ * permission. `BigInt` ids are decimal strings.
+ *
+ * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN` / `SCOPE_MISSING`
+ *   per the permission notes above.
+ */
+export declare class AppAccessAPI {
+    private readonly management;
+    constructor(management: GraphQLClient);
+    /**
+     * List the access tiers defined for an app. **Public.**
+     *
+     * @param appId - Numeric app id (`BigInt` as a decimal string).
+     * @returns The app's tiers, ordered.
+     */
+    tiers(appId: string): Promise<AppAccessTiersQuery['appAccessTiers']>;
+    /**
+     * Return the authenticated caller's access record for an app (which tier they
+     * hold and its status), or `null` if they have none.
+     *
+     * @param appId - Numeric app id.
+     * @returns The caller's {@link AppUserAccess}, or `null`.
+     */
+    myAccess(appId: string): Promise<MyAppAccessQuery['myAppAccess']>;
+    /**
+     * List the users who hold access to an app (paginated). Requires the
+     * `manage_access_tiers` app permission.
+     *
+     * @param appId - Numeric app id.
+     * @param opts - Optional `status` filter and `limit` / `offset` (default
+     *   limit 50).
+     * @returns The matching access records.
+     */
+    usersByApp(appId: string, opts?: {
+        status?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<AppUserAccessByAppQuery['appUserAccessByApp']>;
+    /**
+     * Relay-style cursor pagination over an app's access grants — the preferred
+     * alternative to {@link usersByApp}. Page with `first` plus the previous
+     * page's `pageInfo.endCursor` as `after`; optional `status` filter. Requires
+     * the `manage_access_tiers` app permission. See
+     * https://docs.crowdedkingdoms.com/overview/pagination.
+     *
+     * @param args - `appId` plus optional `status`, `first`, and `after`.
+     * @returns An {@link AppUserAccessConnection}.
+     */
+    usersByAppConnection(args: AppUserAccessConnectionQueryVariables): Promise<AppUserAccessConnectionQuery['appUserAccessConnection']>;
+    /**
+     * List every valid runtime permission key (e.g. `access`, `teleport`,
+     * `update_voxel_data`, `use_voice_chat`) that a tier or grid grant can
+     * reference. **Public.**
+     *
+     * @returns The runtime permission keys.
+     */
+    runtimePermissions(): Promise<RuntimePermissionsQuery['runtimePermissions']>;
+    /**
+     * List org members eligible for a manual app-access grant (those without an
+     * active grant yet). Requires the `manage_access_tiers` app permission. Pair
+     * with {@link grant} to grant the chosen candidate.
+     *
+     * @param appId - Numeric app id.
+     * @returns The candidate users (id + email/gamertag where known).
+     */
+    grantMemberCandidates(appId: string): Promise<AppGrantMemberCandidatesQuery['appGrantMemberCandidates']>;
+    /**
+     * Self-service: claim the app's free/default tier for the authenticated
+     * caller (no admin permission required). Use when an app exposes a free tier
+     * a player can opt into themselves.
+     *
+     * @param appId - Numeric app id.
+     * @returns The caller's new {@link AppUserAccess} record.
+     */
+    claimFree(appId: string): Promise<ClaimFreeAppAccessMutation['claimFreeAppAccess']>;
+    /**
+     * Self-grant access to an app via its default tier for the authenticated
+     * caller, when the caller is an org member of the app's owning org.
+     *
+     * @param appId - Numeric app id.
+     * @returns The caller's new {@link AppUserAccess} record.
+     */
+    grantMine(appId: string): Promise<GrantMyAppAccessMutation['grantMyAppAccess']>;
+    /**
+     * Create a new access tier for an app. Requires the `manage_access_tiers` app
+     * permission.
+     *
+     * @param input - {@link CreateAccessTierInput}: `appId`, `name`, runtime
+     *   `permissions`, pricing/free flags.
+     * @returns The created tier.
+     */
+    createTier(input: CreateAccessTierInput): Promise<CreateAccessTierMutation['createAccessTier']>;
+    /**
+     * Update an existing access tier. Requires the `manage_access_tiers` app
+     * permission.
+     *
+     * @param tierId - Numeric tier id.
+     * @param input - {@link UpdateAccessTierInput} fields to change.
+     * @returns The updated tier.
+     */
+    updateTier(tierId: string, input: UpdateAccessTierInput): Promise<UpdateAccessTierMutation['updateAccessTier']>;
+    /**
+     * Archive (soft-delete) an access tier so it can no longer be granted.
+     * Requires the `manage_access_tiers` app permission.
+     *
+     * @param tierId - Numeric tier id.
+     * @returns The archived tier's new status.
+     */
+    archiveTier(tierId: string): Promise<ArchiveAccessTierMutation['archiveAccessTier']>;
+    /**
+     * Grant a user access to an app at a given tier. Requires the
+     * `manage_access_tiers` app permission. Triggers replica-sync so the grant
+     * (and its grid permissions) reaches the game DB / Buddy.
+     *
+     * @param input - {@link GrantAppAccessInput}: `appId`, `userId`, `tierId`.
+     * @returns The created/updated access record.
+     */
+    grant(input: GrantAppAccessInput): Promise<GrantAppAccessMutation['grantAppAccess']>;
+    /**
+     * Revoke a user's access to an app. Requires the `manage_access_tiers` app
+     * permission.
+     *
+     * @param appId - Numeric app id.
+     * @param userId - Numeric id of the user whose access is revoked.
+     * @returns `true` on success.
+     */
+    revoke(appId: string, userId: string): Promise<RevokeAppAccessMutation['revokeAppAccess']>;
+}
+//# sourceMappingURL=appAccess.d.ts.map

package/dist/domains/appAccess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"appAccess.d.ts","sourceRoot":"","sources":["../../src/domains/appAccess.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAcL,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,uBAAuB,EAC5B,KAAK,4BAA4B,EACjC,KAAK,qCAAqC,EAC1C,KAAK,uBAAuB,EAC5B,KAAK,6BAA6B,EAClC,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACzB,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,aAAa;IAEtD;;;;;OAKG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;IAO1E;;;;;;OAMG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC,aAAa,CAAC,CAAC;IAKvE;;;;;;;;OAQG;IACG,UAAU,CACd,KAAK,EAAE,MAAM,EACb,IAAI,GAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAO,GAC9D,OAAO,CAAC,uBAAuB,CAAC,oBAAoB,CAAC,CAAC;IAUzD;;;;;;;;;OASG;IACG,oBAAoB,CACxB,IAAI,EAAE,qCAAqC,GAC1C,OAAO,CAAC,4BAA4B,CAAC,yBAAyB,CAAC,CAAC;IAQnE;;;;;;OAMG;IACG,kBAAkB,IAAI,OAAO,CACjC,uBAAuB,CAAC,oBAAoB,CAAC,CAC9C;IAKD;;;;;;;OAOG;IACG,qBAAqB,CACzB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,6BAA6B,CAAC,0BAA0B,CAAC,CAAC;IAQrE;;;;;;;OAOG;IACG,SAAS,CACb,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,0BAA0B,CAAC,oBAAoB,CAAC,CAAC;IAO5D;;;;;;OAMG;IACG,SAAS,CACb,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,wBAAwB,CAAC,kBAAkB,CAAC,CAAC;IAOxD;;;;;;;OAOG;IACG,UAAU,CACd,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,wBAAwB,CAAC,kBAAkB,CAAC,CAAC;IAOxD;;;;;;;OAOG;IACG,UAAU,CACd,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,qBAAqB,GAC3B,OAAO,CAAC,wBAAwB,CAAC,kBAAkB,CAAC,CAAC;IAQxD;;;;;;OAMG;IACG,WAAW,CACf,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,yBAAyB,CAAC,mBAAmB,CAAC,CAAC;IAO1D;;;;;;;OAOG;IACG,KAAK,CACT,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,sBAAsB,CAAC,gBAAgB,CAAC,CAAC;IAOpD;;;;;;;OAOG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,uBAAuB,CAAC,iBAAiB,CAAC,CAAC;CAOvD"}