@crowdedkingdoms/crowdyjs 1.0.0

package/dist/domains/payments.js

@@ -0,0 +1,129 @@
+import { MyCheckoutsDocument, MyCheckoutsConnectionDocument, CheckoutsDocument, CheckoutsConnectionDocument, CreateCheckoutDocument, CapturePaypalCheckoutDocument, PaymentEventsDocument, PaymentEventsConnectionDocument, } from '../generated/graphql.js';
+/**
+ * Payment checkouts (wallet top-ups, plan purchases) — exposed as
+ * `client.payments` (and grouped under `client.admin`).
+ *
+ * Targets the **management-api**. {@link create} and {@link mine} require an
+ * authenticated caller and act on their own checkouts; {@link all} is
+ * super-admin only. Amounts are minor currency units (`*Cents`).
+ *
+ * Note: {@link create} starts a real payment-provider checkout (Stripe /
+ * PayPal). In tests use sandbox provider keys only — never trigger real
+ * charges.
+ *
+ * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN` per the notes
+ *   above.
+ */
+export class PaymentsAPI {
+    constructor(management) {
+        this.management = management;
+    }
+    /**
+     * Start a checkout (e.g. an `ORG_WALLET_TOPUP`). Requires authentication.
+     *
+     * @param input - {@link CreateCheckoutInput}: purpose, amount, provider, and
+     *   return URLs.
+     * @returns The created checkout including the provider redirect/approval URL.
+     */
+    async create(input) {
+        const data = await this.management.request(CreateCheckoutDocument, {
+            input,
+        });
+        return data.createCheckout;
+    }
+    /**
+     * List the authenticated caller's own checkouts (newest first).
+     *
+     * @param opts - Optional `limit` / `offset` (default limit 50).
+     * @returns The caller's checkouts.
+     */
+    async mine(opts = {}) {
+        const data = await this.management.request(MyCheckoutsDocument, {
+            limit: opts.limit,
+            offset: opts.offset,
+        });
+        return data.myCheckouts;
+    }
+    /**
+     * List checkouts across all users with an optional filter. **Super-admin
+     * only.**
+     *
+     * @param opts - Optional {@link CheckoutFilterInput} `filter` and `limit` /
+     *   `offset`.
+     * @returns The matching checkouts.
+     */
+    async all(opts = {}) {
+        const data = await this.management.request(CheckoutsDocument, {
+            filter: opts.filter,
+            limit: opts.limit,
+            offset: opts.offset,
+        });
+        return data.checkouts;
+    }
+    /**
+     * Capture an approved PayPal order, finalizing the checkout it belongs to.
+     * Call this after the buyer approves the PayPal order returned by
+     * {@link create}. Requires authentication.
+     *
+     * Pass `idempotencyKey` to make retries safe: replaying with the same key
+     * returns the first result instead of re-capturing.
+     *
+     * @param orderId - The PayPal order id to capture.
+     * @param idempotencyKey - Optional key for safe retries.
+     * @returns The finalized {@link Checkout}.
+     */
+    async capturePaypal(orderId, idempotencyKey) {
+        const data = await this.management.request(CapturePaypalCheckoutDocument, {
+            orderId,
+            idempotencyKey,
+        });
+        return data.capturePaypalCheckout;
+    }
+    /**
+     * Relay-style cursor pagination over the caller's own checkouts — the
+     * preferred alternative to {@link mine}. See
+     * https://docs.crowdedkingdoms.com/overview/pagination.
+     *
+     * @param args - Optional `first` and `after`.
+     * @returns A checkouts connection.
+     */
+    async mineConnection(args = {}) {
+        const data = await this.management.request(MyCheckoutsConnectionDocument, args);
+        return data.myCheckoutsConnection;
+    }
+    /**
+     * Relay-style cursor pagination over all checkouts (with optional filter) —
+     * the preferred alternative to {@link all}. **Super-admin only.**
+     *
+     * @param args - Optional `first`, `after`, and {@link CheckoutFilterInput}.
+     * @returns A checkouts connection.
+     */
+    async allConnection(args = {}) {
+        const data = await this.management.request(CheckoutsConnectionDocument, args);
+        return data.checkoutsConnection;
+    }
+    /**
+     * List provider webhook events (offset pagination). **Super-admin only** — an
+     * audit view of received Stripe/PayPal/SES events.
+     *
+     * @param opts - Optional `limit` / `offset`.
+     * @returns A page of {@link PaymentEventRecord}s.
+     * @remarks Prefer {@link eventsConnection} (Relay cursor pagination); the
+     *   offset args here are deprecated server-side.
+     */
+    async events(opts = {}) {
+        const data = await this.management.request(PaymentEventsDocument, opts);
+        return data.paymentEvents;
+    }
+    /**
+     * Relay-style cursor pagination over provider webhook events. **Super-admin
+     * only.** See https://docs.crowdedkingdoms.com/overview/pagination.
+     *
+     * @param args - Optional `first` and `after`.
+     * @returns A payment-events connection.
+     */
+    async eventsConnection(args = {}) {
+        const data = await this.management.request(PaymentEventsConnectionDocument, args);
+        return data.paymentEventsConnection;
+    }
+}

package/dist/domains/platform.d.ts

@@ -0,0 +1,49 @@
+import type { GraphQLClient } from '../client.js';
+/**
+ * Public platform discovery returned by {@link PlatformAPI.config}: how SDKs
+ * find the shared game-api so they can route apps deployed to the shared
+ * environment. All fields are public (no auth required to read them).
+ */
+export interface PlatformConfig {
+    /** Shared game-api HTTP/GraphQL root for shared-environment apps; `null` if unset. */
+    sharedGameApiUrl: string | null;
+    /** Shared game-api WebSocket root (subscriptions / UDP proxy); `null` if unset. */
+    sharedGameApiWsUrl: string | null;
+    /** Free shared app slots an org gets before a paid subscription is required. */
+    freeAppsPerOrg: number;
+}
+/**
+ * Public platform discovery — exposed as `client.platform`.
+ *
+ * Targets the **management-api** (every call routes to `managementUrl`).
+ * **Public**: no authentication required. Lets a client discover the shared
+ * game-api URL (for apps published to the shared environment) *before* it has a
+ * per-app endpoint, then build a game-api `CrowdyClient` against it.
+ *
+ * @example
+ * ```ts
+ * const base = createCrowdyClient({ managementUrl: 'https://api.example.com' });
+ * const cfg = await base.platform.config();
+ * const gameClient = createCrowdyClient({
+ *   managementUrl: 'https://api.example.com',
+ *   httpUrl: cfg.sharedGameApiUrl ?? undefined,
+ *   wsUrl: cfg.sharedGameApiWsUrl ?? undefined,
+ *   tokenStore: base.session.tokenStore,
+ * });
+ * ```
+ */
+export declare class PlatformAPI {
+    private readonly management;
+    constructor(management: GraphQLClient);
+    /**
+     * Fetch public platform discovery: the shared game-api URL clients use for
+     * shared-environment apps, plus the free shared-app quota. **Public** — no
+     * authentication required.
+     *
+     * @returns A {@link PlatformConfig} (`sharedGameApiUrl`, `sharedGameApiWsUrl`,
+     *   and `freeAppsPerOrg`).
+     * @throws {CrowdyGraphQLError} on transport/validation failures.
+     */
+    config(): Promise<PlatformConfig>;
+}
+//# sourceMappingURL=platform.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../src/domains/platform.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,sFAAsF;IACtF,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mFAAmF;IACnF,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,gFAAgF;IAChF,cAAc,EAAE,MAAM,CAAC;CACxB;AAiBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,WAAW;IACV,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,aAAa;IAEtD;;;;;;;;OAQG;IACG,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;CAIxC"}

package/dist/domains/platform.js

@@ -0,0 +1,50 @@
+import { parse } from 'graphql';
+// Hand-written document so the SDK can discover the shared game-api URL even
+// before codegen picks up the new schema (see src/operations/platform/).
+const PlatformConfigDocument = parse(/* GraphQL */ `
+  query PlatformConfig {
+    platformConfig {
+      sharedGameApiUrl
+      sharedGameApiWsUrl
+      freeAppsPerOrg
+    }
+  }
+`);
+/**
+ * Public platform discovery — exposed as `client.platform`.
+ *
+ * Targets the **management-api** (every call routes to `managementUrl`).
+ * **Public**: no authentication required. Lets a client discover the shared
+ * game-api URL (for apps published to the shared environment) *before* it has a
+ * per-app endpoint, then build a game-api `CrowdyClient` against it.
+ *
+ * @example
+ * ```ts
+ * const base = createCrowdyClient({ managementUrl: 'https://api.example.com' });
+ * const cfg = await base.platform.config();
+ * const gameClient = createCrowdyClient({
+ *   managementUrl: 'https://api.example.com',
+ *   httpUrl: cfg.sharedGameApiUrl ?? undefined,
+ *   wsUrl: cfg.sharedGameApiWsUrl ?? undefined,
+ *   tokenStore: base.session.tokenStore,
+ * });
+ * ```
+ */
+export class PlatformAPI {
+    constructor(management) {
+        this.management = management;
+    }
+    /**
+     * Fetch public platform discovery: the shared game-api URL clients use for
+     * shared-environment apps, plus the free shared-app quota. **Public** — no
+     * authentication required.
+     *
+     * @returns A {@link PlatformConfig} (`sharedGameApiUrl`, `sharedGameApiWsUrl`,
+     *   and `freeAppsPerOrg`).
+     * @throws {CrowdyGraphQLError} on transport/validation failures.
+     */
+    async config() {
+        const data = await this.management.request(PlatformConfigDocument, {});
+        return data.platformConfig;
+    }
+}

package/dist/domains/quotas.d.ts

@@ -0,0 +1,62 @@
+import type { GraphQLClient } from '../client.js';
+import { type QuotasForOrgQuery, type QuotasForAppQuery, type EffectiveQuotaQuery, type SetQuotaMutation, type DeleteQuotaMutation, type SetQuotaInput } from '../generated/graphql.js';
+/**
+ * Usage quotas at the org and app scope — exposed as `client.quotas` (and
+ * grouped under `client.admin`).
+ *
+ * Targets the **management-api**. Reads require the `view_usage` org/app
+ * permission; {@link set} / {@link remove} require `manage_quotas` (global
+ * quotas are super-admin only). A quota is keyed by a `metric` string; the
+ * effective value resolves app → org → platform default.
+ *
+ * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN` / `SCOPE_MISSING`
+ *   per the permission notes above.
+ */
+export declare class QuotasAPI {
+    private readonly management;
+    constructor(management: GraphQLClient);
+    /**
+     * List the quotas configured directly on an organization. Requires the
+     * `view_usage` org permission.
+     *
+     * @param orgId - Numeric org id (`BigInt` as a decimal string).
+     * @returns The org's quotas.
+     */
+    forOrg(orgId: string): Promise<QuotasForOrgQuery['quotasForOrg']>;
+    /**
+     * List the quotas configured directly on an app. Requires the `view_usage`
+     * app permission.
+     *
+     * @param appId - Numeric app id.
+     * @returns The app's quotas.
+     */
+    forApp(appId: string): Promise<QuotasForAppQuery['quotasForApp']>;
+    /**
+     * Resolve the effective value of a metric for an org and/or app (app overrides
+     * org overrides platform default). Requires `view_usage` on the scope.
+     *
+     * @param metric - The quota metric key (e.g. `"replication_messages"`).
+     * @param scope - Optional `orgId` and/or `appId` to resolve against.
+     * @returns The effective quota for the metric.
+     */
+    effective(metric: string, scope?: {
+        orgId?: string;
+        appId?: string;
+    }): Promise<EffectiveQuotaQuery['effectiveQuota']>;
+    /**
+     * Create or update a quota at an org or app scope. Requires `manage_quotas`
+     * (super-admin for platform-global quotas).
+     *
+     * @param input - {@link SetQuotaInput}: scope ids, `metric`, and `limit`.
+     * @returns The created/updated quota.
+     */
+    set(input: SetQuotaInput): Promise<SetQuotaMutation['setQuota']>;
+    /**
+     * Delete a quota by id. Requires `manage_quotas` on the owning scope.
+     *
+     * @param quotaId - Numeric quota id.
+     * @returns `true` on success.
+     */
+    remove(quotaId: string): Promise<DeleteQuotaMutation['deleteQuota']>;
+}
+//# sourceMappingURL=quotas.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"quotas.d.ts","sourceRoot":"","sources":["../../src/domains/quotas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAML,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACxB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,aAAa,EACnB,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;GAWG;AACH,qBAAa,SAAS;IACR,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,aAAa;IAEtD;;;;;;OAMG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAKvE;;;;;;OAMG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAKvE;;;;;;;OAOG;IACG,SAAS,CACb,MAAM,EAAE,MAAM,EACd,KAAK,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAO,GAC7C,OAAO,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;IASjD;;;;;;OAMG;IACG,GAAG,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC,UAAU,CAAC,CAAC;IAKtE;;;;;OAKG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC,aAAa,CAAC,CAAC;CAM3E"}

package/dist/domains/quotas.js

@@ -0,0 +1,79 @@
+import { QuotasForOrgDocument, QuotasForAppDocument, EffectiveQuotaDocument, SetQuotaDocument, DeleteQuotaDocument, } from '../generated/graphql.js';
+/**
+ * Usage quotas at the org and app scope — exposed as `client.quotas` (and
+ * grouped under `client.admin`).
+ *
+ * Targets the **management-api**. Reads require the `view_usage` org/app
+ * permission; {@link set} / {@link remove} require `manage_quotas` (global
+ * quotas are super-admin only). A quota is keyed by a `metric` string; the
+ * effective value resolves app → org → platform default.
+ *
+ * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN` / `SCOPE_MISSING`
+ *   per the permission notes above.
+ */
+export class QuotasAPI {
+    constructor(management) {
+        this.management = management;
+    }
+    /**
+     * List the quotas configured directly on an organization. Requires the
+     * `view_usage` org permission.
+     *
+     * @param orgId - Numeric org id (`BigInt` as a decimal string).
+     * @returns The org's quotas.
+     */
+    async forOrg(orgId) {
+        const data = await this.management.request(QuotasForOrgDocument, { orgId });
+        return data.quotasForOrg;
+    }
+    /**
+     * List the quotas configured directly on an app. Requires the `view_usage`
+     * app permission.
+     *
+     * @param appId - Numeric app id.
+     * @returns The app's quotas.
+     */
+    async forApp(appId) {
+        const data = await this.management.request(QuotasForAppDocument, { appId });
+        return data.quotasForApp;
+    }
+    /**
+     * Resolve the effective value of a metric for an org and/or app (app overrides
+     * org overrides platform default). Requires `view_usage` on the scope.
+     *
+     * @param metric - The quota metric key (e.g. `"replication_messages"`).
+     * @param scope - Optional `orgId` and/or `appId` to resolve against.
+     * @returns The effective quota for the metric.
+     */
+    async effective(metric, scope = {}) {
+        const data = await this.management.request(EffectiveQuotaDocument, {
+            metric,
+            orgId: scope.orgId,
+            appId: scope.appId,
+        });
+        return data.effectiveQuota;
+    }
+    /**
+     * Create or update a quota at an org or app scope. Requires `manage_quotas`
+     * (super-admin for platform-global quotas).
+     *
+     * @param input - {@link SetQuotaInput}: scope ids, `metric`, and `limit`.
+     * @returns The created/updated quota.
+     */
+    async set(input) {
+        const data = await this.management.request(SetQuotaDocument, { input });
+        return data.setQuota;
+    }
+    /**
+     * Delete a quota by id. Requires `manage_quotas` on the owning scope.
+     *
+     * @param quotaId - Numeric quota id.
+     * @returns `true` on success.
+     */
+    async remove(quotaId) {
+        const data = await this.management.request(DeleteQuotaDocument, {
+            quotaId,
+        });
+        return data.deleteQuota;
+    }
+}

package/dist/domains/serverStatus.d.ts

@@ -0,0 +1,90 @@
+import type { GraphQLClient } from '../client.js';
+import { type ServerWithLeastClientsQuery, type GraphqlServersQuery, type ActiveGraphQlServersQuery, type VersionInfoQuery, type GameClientBootstrapQuery, type GameClientBootstrapQueryVariables } from '../generated/graphql.js';
+/**
+ * Server discovery, version, and client-bootstrap queries on the **game-api**.
+ * Exposed as `client.serverStatus`.
+ *
+ * This is the **client bootstrap path**: call {@link ServerStatusAPI.gameClientBootstrap}
+ * once after login to get everything a play session needs (identity, version
+ * floors, UDP status, realtime protocol details, and spatial limits) in a single
+ * round-trip, and use {@link ServerStatusAPI.versionInfo} for standalone version
+ * discovery / update gating. The remaining queries expose UDP/GraphQL server
+ * fleet info for discovery and routing.
+ *
+ * NOTE: there is no separate "buddy server" query in the schema — the
+ * least-loaded UDP game server is selected automatically when a session is
+ * opened. {@link ServerStatusAPI.serverWithLeastClients} returns a hint of which
+ * UDP server a new session would land on.
+ *
+ * Auth varies per method: {@link ServerStatusAPI.gameClientBootstrap} and
+ * {@link ServerStatusAPI.serverWithLeastClients} require a Bearer game token (set
+ * via `client.auth.login()` or `client.setToken()`), while
+ * {@link ServerStatusAPI.listAll}, {@link ServerStatusAPI.listActiveGraphqlServers}
+ * and {@link ServerStatusAPI.versionInfo} need no authentication. `appId` is a
+ * `BigInt` sent as a decimal string.
+ */
+export declare class ServerStatusAPI {
+    private gql;
+    constructor(gql: GraphQLClient);
+    /**
+     * Pick a low-load UDP game server for a **native (direct-UDP)** client to
+     * connect to: returns a random server from the least-loaded ~20% (by client
+     * count) of `ReadyForClients` servers to spread load. As a side effect it
+     * authorizes the token's P2P session with the chosen Buddy so the native
+     * client's spatial datagrams are accepted; connect the client to the returned
+     * `ip4` + `clientPort`. Browser clients should instead use the UDP proxy
+     * (`client.udp` / `udpNotifications`) and do not need this.
+     *
+     * @returns A {@link ServerStatus} describing the selected UDP server.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` if no valid game token is
+     *   present.
+     */
+    serverWithLeastClients(): Promise<ServerWithLeastClientsQuery['serverWithLeastClients']>;
+    /**
+     * List every registered GraphQL API server (both `management-api` and
+     * `game-api` kinds), regardless of health/state — for service discovery. To
+     * route clients, prefer {@link ServerStatusAPI.listActiveGraphqlServers}
+     * (healthy only). No authentication required.
+     *
+     * @returns Every registered {@link GraphQLServer}.
+     */
+    listAll(): Promise<GraphqlServersQuery['graphqlServers']>;
+    /**
+     * List only healthy GraphQL API servers (`status = ReadyForClients`) for client
+     * routing/discovery. No authentication required.
+     *
+     * @returns The healthy {@link GraphQLServer}s.
+     */
+    listActiveGraphqlServers(): Promise<ActiveGraphQlServersQuery['activeGraphQLServers']>;
+    /**
+     * Get the current server version and the minimum client version the server
+     * accepts. No authentication required — compare your build against
+     * `minimumClientVersion` before connecting and prompt an update if it is too
+     * old.
+     *
+     * @returns A {@link ServerVersionInfo} (`serverVersion` + `minimumClientVersion`,
+     *   each a major/minor/patch/build {@link VersionInfo}).
+     */
+    versionInfo(): Promise<VersionInfoQuery['versionInfo']>;
+    /**
+     * Single startup payload for browser game clients: the authenticated user,
+     * server/min-client version requirements, current UDP proxy status, realtime
+     * protocol details (subprotocol + subscription name), and the spatial send
+     * limits/constants. Read-only — does **not** open a UDP proxy session. Call this
+     * once after login to initialize a play session instead of issuing several
+     * separate queries.
+     *
+     * @param appId - The app (game) the client is initializing for (`BigInt` as a
+     *   decimal string). Scopes the returned UDP status and mirrors the app's
+     *   entitlements; reuse the same `appId` when subscribing and on every spatial
+     *   send.
+     * @returns A {@link GameClientBootstrap}: `me`, `versionInfo`,
+     *   `udpProxyConnectionStatus`, `realtimeProtocol`, `subscriptionName`, and the
+     *   spatial limits `maxReplicationDistance` (max `distance` fan-out, in chunk
+     *   units), `maxDecayRate`, and `sequenceNumberModulo` (256).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` without a valid game token, or
+     *   `FORBIDDEN` if not entitled to the app.
+     */
+    gameClientBootstrap(appId: GameClientBootstrapQueryVariables['appId']): Promise<GameClientBootstrapQuery['gameClientBootstrap']>;
+}
+//# sourceMappingURL=serverStatus.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serverStatus.d.ts","sourceRoot":"","sources":["../../src/domains/serverStatus.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,EAEL,KAAK,2BAA2B,EAEhC,KAAK,mBAAmB,EAExB,KAAK,yBAAyB,EAE9B,KAAK,gBAAgB,EAErB,KAAK,wBAAwB,EAC7B,KAAK,iCAAiC,EACvC,MAAM,yBAAyB,CAAC;AAEjC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,eAAe;IACd,OAAO,CAAC,GAAG;gBAAH,GAAG,EAAE,aAAa;IAEtC;;;;;;;;;;;;OAYG;IACG,sBAAsB,IAAI,OAAO,CAAC,2BAA2B,CAAC,wBAAwB,CAAC,CAAC;IAK9F;;;;;;;OAOG;IACG,OAAO,IAAI,OAAO,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;IAK/D;;;;;OAKG;IACG,wBAAwB,IAAI,OAAO,CAAC,yBAAyB,CAAC,sBAAsB,CAAC,CAAC;IAK5F;;;;;;;;OAQG;IACG,WAAW,IAAI,OAAO,CAAC,gBAAgB,CAAC,aAAa,CAAC,CAAC;IAK7D;;;;;;;;;;;;;;;;;;OAkBG;IACG,mBAAmB,CACvB,KAAK,EAAE,iCAAiC,CAAC,OAAO,CAAC,GAChD,OAAO,CAAC,wBAAwB,CAAC,qBAAqB,CAAC,CAAC;CAI5D"}

package/dist/domains/serverStatus.js

@@ -0,0 +1,104 @@
+import { ServerWithLeastClientsDocument, GraphqlServersDocument, ActiveGraphQlServersDocument, VersionInfoDocument, GameClientBootstrapDocument, } from '../generated/graphql.js';
+/**
+ * Server discovery, version, and client-bootstrap queries on the **game-api**.
+ * Exposed as `client.serverStatus`.
+ *
+ * This is the **client bootstrap path**: call {@link ServerStatusAPI.gameClientBootstrap}
+ * once after login to get everything a play session needs (identity, version
+ * floors, UDP status, realtime protocol details, and spatial limits) in a single
+ * round-trip, and use {@link ServerStatusAPI.versionInfo} for standalone version
+ * discovery / update gating. The remaining queries expose UDP/GraphQL server
+ * fleet info for discovery and routing.
+ *
+ * NOTE: there is no separate "buddy server" query in the schema — the
+ * least-loaded UDP game server is selected automatically when a session is
+ * opened. {@link ServerStatusAPI.serverWithLeastClients} returns a hint of which
+ * UDP server a new session would land on.
+ *
+ * Auth varies per method: {@link ServerStatusAPI.gameClientBootstrap} and
+ * {@link ServerStatusAPI.serverWithLeastClients} require a Bearer game token (set
+ * via `client.auth.login()` or `client.setToken()`), while
+ * {@link ServerStatusAPI.listAll}, {@link ServerStatusAPI.listActiveGraphqlServers}
+ * and {@link ServerStatusAPI.versionInfo} need no authentication. `appId` is a
+ * `BigInt` sent as a decimal string.
+ */
+export class ServerStatusAPI {
+    constructor(gql) {
+        this.gql = gql;
+    }
+    /**
+     * Pick a low-load UDP game server for a **native (direct-UDP)** client to
+     * connect to: returns a random server from the least-loaded ~20% (by client
+     * count) of `ReadyForClients` servers to spread load. As a side effect it
+     * authorizes the token's P2P session with the chosen Buddy so the native
+     * client's spatial datagrams are accepted; connect the client to the returned
+     * `ip4` + `clientPort`. Browser clients should instead use the UDP proxy
+     * (`client.udp` / `udpNotifications`) and do not need this.
+     *
+     * @returns A {@link ServerStatus} describing the selected UDP server.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` if no valid game token is
+     *   present.
+     */
+    async serverWithLeastClients() {
+        const data = await this.gql.request(ServerWithLeastClientsDocument, undefined);
+        return data.serverWithLeastClients;
+    }
+    /**
+     * List every registered GraphQL API server (both `management-api` and
+     * `game-api` kinds), regardless of health/state — for service discovery. To
+     * route clients, prefer {@link ServerStatusAPI.listActiveGraphqlServers}
+     * (healthy only). No authentication required.
+     *
+     * @returns Every registered {@link GraphQLServer}.
+     */
+    async listAll() {
+        const data = await this.gql.request(GraphqlServersDocument, undefined);
+        return data.graphqlServers;
+    }
+    /**
+     * List only healthy GraphQL API servers (`status = ReadyForClients`) for client
+     * routing/discovery. No authentication required.
+     *
+     * @returns The healthy {@link GraphQLServer}s.
+     */
+    async listActiveGraphqlServers() {
+        const data = await this.gql.request(ActiveGraphQlServersDocument, undefined);
+        return data.activeGraphQLServers;
+    }
+    /**
+     * Get the current server version and the minimum client version the server
+     * accepts. No authentication required — compare your build against
+     * `minimumClientVersion` before connecting and prompt an update if it is too
+     * old.
+     *
+     * @returns A {@link ServerVersionInfo} (`serverVersion` + `minimumClientVersion`,
+     *   each a major/minor/patch/build {@link VersionInfo}).
+     */
+    async versionInfo() {
+        const data = await this.gql.request(VersionInfoDocument, undefined);
+        return data.versionInfo;
+    }
+    /**
+     * Single startup payload for browser game clients: the authenticated user,
+     * server/min-client version requirements, current UDP proxy status, realtime
+     * protocol details (subprotocol + subscription name), and the spatial send
+     * limits/constants. Read-only — does **not** open a UDP proxy session. Call this
+     * once after login to initialize a play session instead of issuing several
+     * separate queries.
+     *
+     * @param appId - The app (game) the client is initializing for (`BigInt` as a
+     *   decimal string). Scopes the returned UDP status and mirrors the app's
+     *   entitlements; reuse the same `appId` when subscribing and on every spatial
+     *   send.
+     * @returns A {@link GameClientBootstrap}: `me`, `versionInfo`,
+     *   `udpProxyConnectionStatus`, `realtimeProtocol`, `subscriptionName`, and the
+     *   spatial limits `maxReplicationDistance` (max `distance` fan-out, in chunk
+     *   units), `maxDecayRate`, and `sequenceNumberModulo` (256).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` without a valid game token, or
+     *   `FORBIDDEN` if not entitled to the app.
+     */
+    async gameClientBootstrap(appId) {
+        const data = await this.gql.request(GameClientBootstrapDocument, { appId });
+        return data.gameClientBootstrap;
+    }
+}