@crowdedkingdoms/crowdyjs 1.0.0

package/dist/domains/appAccess.js

@@ -0,0 +1,198 @@
+import { AppAccessTiersDocument, MyAppAccessDocument, AppUserAccessByAppDocument, AppUserAccessConnectionDocument, RuntimePermissionsDocument, AppGrantMemberCandidatesDocument, ClaimFreeAppAccessDocument, GrantMyAppAccessDocument, CreateAccessTierDocument, UpdateAccessTierDocument, ArchiveAccessTierDocument, GrantAppAccessDocument, RevokeAppAccessDocument, } 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 class AppAccessAPI {
+    constructor(management) {
+        this.management = management;
+    }
+    /**
+     * 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.
+     */
+    async tiers(appId) {
+        const data = await this.management.request(AppAccessTiersDocument, {
+            appId,
+        });
+        return data.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`.
+     */
+    async myAccess(appId) {
+        const data = await this.management.request(MyAppAccessDocument, { appId });
+        return data.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.
+     */
+    async usersByApp(appId, opts = {}) {
+        const data = await this.management.request(AppUserAccessByAppDocument, {
+            appId,
+            status: opts.status,
+            limit: opts.limit,
+            offset: opts.offset,
+        });
+        return data.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}.
+     */
+    async usersByAppConnection(args) {
+        const data = await this.management.request(AppUserAccessConnectionDocument, args);
+        return data.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.
+     */
+    async runtimePermissions() {
+        const data = await this.management.request(RuntimePermissionsDocument);
+        return data.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).
+     */
+    async grantMemberCandidates(appId) {
+        const data = await this.management.request(AppGrantMemberCandidatesDocument, { appId });
+        return data.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.
+     */
+    async claimFree(appId) {
+        const data = await this.management.request(ClaimFreeAppAccessDocument, {
+            appId,
+        });
+        return data.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.
+     */
+    async grantMine(appId) {
+        const data = await this.management.request(GrantMyAppAccessDocument, {
+            appId,
+        });
+        return data.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.
+     */
+    async createTier(input) {
+        const data = await this.management.request(CreateAccessTierDocument, {
+            input,
+        });
+        return data.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.
+     */
+    async updateTier(tierId, input) {
+        const data = await this.management.request(UpdateAccessTierDocument, {
+            tierId,
+            input,
+        });
+        return data.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.
+     */
+    async archiveTier(tierId) {
+        const data = await this.management.request(ArchiveAccessTierDocument, {
+            tierId,
+        });
+        return data.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.
+     */
+    async grant(input) {
+        const data = await this.management.request(GrantAppAccessDocument, {
+            input,
+        });
+        return data.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.
+     */
+    async revoke(appId, userId) {
+        const data = await this.management.request(RevokeAppAccessDocument, {
+            appId,
+            userId,
+        });
+        return data.revokeAppAccess;
+    }
+}

package/dist/domains/apps.d.ts

@@ -0,0 +1,192 @@
+import type { GraphQLClient } from '../client.js';
+import { type AppQuery, type AppBySlugQuery, type MyAppsQuery, type AppsForOrgQuery, type MarketplaceAppsQuery, type MarketplaceAppsQueryVariables, type AppsConnectionQuery, type AppsConnectionQueryVariables, type CreateAppMutation, type UpdateAppMutation, type ArchiveAppMutation, type SetAppVisibilityMutation, type CreateAppInput, type UpdateAppInput, type AppVisibility } from '../generated/graphql.js';
+/**
+ * The minimal routing tuple the SDK derives from an `App` row: just enough to
+ * decide which game-api endpoint should serve a given app. Returned by
+ * {@link AppsAPI.routeFor}.
+ */
+export interface AppRoute {
+    /** Numeric id of the app (`BigInt` as a decimal string). */
+    appId: string;
+    /**
+     * `true` when the app's runtime data lives in a dedicated per-tenant game-api
+     * database rather than the shared game-api. Used together with `gameApiUrl` to
+     * route gameplay calls.
+     */
+    splitMode: boolean;
+    /**
+     * Where the app runs: `'none'` (draft / not deployed), `'shared'` (the shared
+     * game-api), or `'dedicated'` (a provisioned per-tenant environment). `null`
+     * until the schema/codegen expose it.
+     */
+    deploymentTarget: string | null;
+    /**
+     * The game-api base URL to route gameplay to. Set for BOTH dedicated
+     * (split-mode) and shared-environment apps. When non-null, build a game-api
+     * client against it; when `null`, fall back to the constructor `httpUrl`.
+     */
+    gameApiUrl: string | null;
+}
+/**
+ * App discovery & game-api routing — exposed as `client.apps`.
+ *
+ * Targets the **management-api** (every call routes to `managementUrl`), where
+ * the apps catalog lives. After the database split an app may be served by its
+ * own per-tenant cks-game-api; the catalog returns each app's `gameApiUrl` so
+ * you can build a per-app `CrowdyClient` against the correct endpoint (see
+ * {@link routeFor} / {@link AppRoute}).
+ *
+ * Auth: {@link appBySlug} is **public** (no session; resolves unlisted or draft
+ * apps when the exact slugs are known). {@link app}, {@link myApps}, and
+ * {@link routeFor} require authentication (any signed-in user) and otherwise
+ * throw {@link CrowdyGraphQLError} with `UNAUTHENTICATED`; note {@link app} does
+ * not enforce org/app permissions. `BigInt` ids such as `appId` and `orgId` are
+ * decimal strings.
+ *
+ * @example
+ * ```ts
+ * const base = createCrowdyClient({
+ *   managementUrl: 'https://api.example.com',
+ *   httpUrl: 'https://legacy-game-api.example.com', // pre-split fallback
+ * });
+ * await base.auth.login({ email, password });
+ *
+ * const route = await base.apps.routeFor(appId);
+ * if (route.gameApiUrl) {
+ *   // route gameplay to the app's resolved game-api endpoint
+ *   const perAppClient = createCrowdyClient({
+ *     managementUrl: 'https://api.example.com',
+ *     httpUrl: route.gameApiUrl,
+ *     wsUrl: route.gameApiUrl.replace(/^http/, 'ws'),
+ *     tokenStore: base.session.tokenStore,
+ *   });
+ * }
+ * ```
+ */
+export declare class AppsAPI {
+    private readonly management;
+    constructor(management: GraphQLClient);
+    /**
+     * Fetch a single app by its numeric id. Requires authentication (any signed-in
+     * user); does **not** enforce org/app permissions, so it can read apps the
+     * caller does not own, of any visibility/status. Prefer {@link appBySlug} for
+     * slug-based marketplace lookups.
+     *
+     * @param appId - Numeric id of the app (`BigInt` as a decimal string).
+     * @returns The {@link App}, or `null` if the id does not exist.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` if the caller is not signed in.
+     */
+    app(appId: string): Promise<AppQuery['app']>;
+    /**
+     * Look up a single app by its org slug + app slug (the marketplace URL path).
+     * **Public**: no authentication required, and not filtered by visibility or
+     * status — it can resolve unlisted or draft apps when the exact slugs are
+     * known.
+     *
+     * @param orgSlug - URL slug of the owning organization (e.g. `"acme"` in the
+     *   path `/acme/my-game`).
+     * @param appSlug - URL slug of the app within the org (e.g. `"my-game"`);
+     *   unique per org.
+     * @returns The {@link App}, or `null` if no matching app exists.
+     * @throws {CrowdyGraphQLError} on transport/validation failures.
+     */
+    appBySlug(orgSlug: string, appSlug: string): Promise<AppBySlugQuery['appBySlug']>;
+    /**
+     * List the apps the authenticated caller can see in their account: those owned
+     * by an org they are an active member of, OR those where they hold an active
+     * access grant. Includes apps of any visibility/status (e.g. accessible
+     * drafts), ordered newest-first. Requires authentication.
+     *
+     * @returns The caller's accessible {@link App}s (an empty array if none).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` if the caller is not signed in.
+     */
+    myApps(): Promise<MyAppsQuery['myApps']>;
+    /**
+     * Convenience wrapper over {@link app} that returns just the {@link AppRoute}
+     * routing tuple for an app — i.e. which game-api endpoint should serve it. If
+     * the app row is missing or the API does not expose the split-mode fields yet,
+     * returns a safe default (`{ appId, splitMode: false, deploymentTarget: null,
+     * gameApiUrl: null }`) so the caller keeps using the legacy single-endpoint
+     * deployment.
+     *
+     * @param appId - Numeric id of the app (`BigInt` as a decimal string).
+     * @returns The {@link AppRoute}; route gameplay to `gameApiUrl` when non-null,
+     *   otherwise fall back to the constructor `httpUrl`.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` (it calls {@link app} under
+     *   the hood).
+     */
+    routeFor(appId: string): Promise<AppRoute>;
+    /**
+     * List the apps owned by an organization (by org slug). Studio-admin read —
+     * requires the caller to be a member of the org.
+     *
+     * @param orgSlug - URL slug of the owning organization.
+     * @returns The org's {@link App}s.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN`.
+     */
+    forOrg(orgSlug: string): Promise<AppsForOrgQuery['appsForOrg']>;
+    /**
+     * List the public marketplace apps (LIVE + PUBLIC only) with offset
+     * pagination. **Public** — no session required.
+     *
+     * @param opts - Optional {@link AppMarketplaceFilterInput} `filter` and
+     *   `limit` / `offset`.
+     * @returns A page of marketplace apps.
+     * @remarks Prefer {@link marketplaceConnection} (Relay cursor pagination) for
+     *   large catalogs; the offset args here are deprecated server-side.
+     */
+    marketplace(opts?: {
+        filter?: MarketplaceAppsQueryVariables['filter'];
+        limit?: MarketplaceAppsQueryVariables['limit'];
+        offset?: MarketplaceAppsQueryVariables['offset'];
+    }): Promise<MarketplaceAppsQuery['apps']>;
+    /**
+     * Relay-style cursor pagination over the public marketplace — the preferred
+     * alternative to {@link marketplace}. **Public.** See
+     * https://docs.crowdedkingdoms.com/overview/pagination.
+     *
+     * @param args - Optional `first`, `after`, and {@link AppMarketplaceFilterInput}.
+     * @returns An apps connection.
+     */
+    marketplaceConnection(args?: AppsConnectionQueryVariables): Promise<AppsConnectionQuery['appsConnection']>;
+    /**
+     * Create a new app under an organization. Requires the `manage_apps` org
+     * permission. The new app auto-provisions an open-by-default access tier.
+     *
+     * @param input - {@link CreateAppInput}: `orgId`, `name`, `slug`, optional
+     *   `description`/`visibility`/`metadata`.
+     * @returns The created {@link App}.
+     * @throws {CrowdyGraphQLError} `FORBIDDEN`/`SCOPE_MISSING` without
+     *   `manage_apps`, or `BAD_USER_INPUT` (e.g. duplicate slug).
+     */
+    create(input: CreateAppInput): Promise<CreateAppMutation['createApp']>;
+    /**
+     * Update an app's mutable fields. Requires the `manage_apps` app permission.
+     *
+     * @param appId - Numeric app id.
+     * @param input - {@link UpdateAppInput} fields to change.
+     * @returns The updated {@link App}.
+     * @throws {CrowdyGraphQLError} `FORBIDDEN`/`SCOPE_MISSING` without
+     *   `manage_apps`.
+     */
+    update(appId: string, input: UpdateAppInput): Promise<UpdateAppMutation['updateApp']>;
+    /**
+     * Archive (soft-delete) an app. Requires the `manage_apps` app permission.
+     *
+     * @param appId - Numeric app id.
+     * @returns The archived app's new status.
+     * @throws {CrowdyGraphQLError} `FORBIDDEN`/`SCOPE_MISSING` without
+     *   `manage_apps`.
+     */
+    archive(appId: string): Promise<ArchiveAppMutation['archiveApp']>;
+    /**
+     * Override an app's marketplace visibility. **Super-admin only.**
+     *
+     * @param appId - Numeric app id.
+     * @param visibility - The new {@link AppVisibility}.
+     * @returns The app's updated visibility.
+     * @throws {CrowdyGraphQLError} `FORBIDDEN` for non-super-admins.
+     */
+    setVisibility(appId: string, visibility: AppVisibility): Promise<SetAppVisibilityMutation['setAppVisibility']>;
+}
+//# sourceMappingURL=apps.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"apps.d.ts","sourceRoot":"","sources":["../../src/domains/apps.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAWL,KAAK,QAAQ,EAEb,KAAK,cAAc,EAEnB,KAAK,WAAW,EAChB,KAAK,eAAe,EACpB,KAAK,oBAAoB,EACzB,KAAK,6BAA6B,EAClC,KAAK,mBAAmB,EACxB,KAAK,4BAA4B,EACjC,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,EAC7B,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,yBAAyB,CAAC;AAEjC;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,4DAA4D;IAC5D,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;;;OAIG;IACH,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,OAAO;IACN,OAAO,CAAC,QAAQ,CAAC,UAAU;gBAAV,UAAU,EAAE,aAAa;IAEtD;;;;;;;;;OASG;IACG,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAQlD;;;;;;;;;;;;OAYG;IACG,SAAS,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;IAQvC;;;;;;;;OAQG;IACG,MAAM,IAAI,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAQ9C;;;;;;;;;;;;;OAaG;IACG,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAYhD;;;;;;;OAOG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,YAAY,CAAC,CAAC;IAKrE;;;;;;;;;OASG;IACG,WAAW,CACf,IAAI,GAAE;QACJ,MAAM,CAAC,EAAE,6BAA6B,CAAC,QAAQ,CAAC,CAAC;QACjD,KAAK,CAAC,EAAE,6BAA6B,CAAC,OAAO,CAAC,CAAC;QAC/C,MAAM,CAAC,EAAE,6BAA6B,CAAC,QAAQ,CAAC,CAAC;KAC7C,GACL,OAAO,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAKxC;;;;;;;OAOG;IACG,qBAAqB,CACzB,IAAI,GAAE,4BAAiC,GACtC,OAAO,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;IAKjD;;;;;;;;;OASG;IACG,MAAM,CACV,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAK1C;;;;;;;;OAQG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC;IAQ1C;;;;;;;OAOG;IACG,OAAO,CACX,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAC;IAK5C;;;;;;;OAOG;IACG,aAAa,CACjB,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,aAAa,GACxB,OAAO,CAAC,wBAAwB,CAAC,kBAAkB,CAAC,CAAC;CAOzD"}

package/dist/domains/apps.js

@@ -0,0 +1,217 @@
+import { AppDocument, AppBySlugDocument, MyAppsDocument, AppsForOrgDocument, MarketplaceAppsDocument, AppsConnectionDocument, CreateAppDocument, UpdateAppDocument, ArchiveAppDocument, SetAppVisibilityDocument, } from '../generated/graphql.js';
+function appRouteFromAppRow(row) {
+    if (!row || typeof row !== 'object')
+        return null;
+    const r = row;
+    if (typeof r.appId !== 'string')
+        return null;
+    return {
+        appId: r.appId,
+        splitMode: typeof r.splitMode === 'boolean' ? r.splitMode : false,
+        deploymentTarget: typeof r.deploymentTarget === 'string' ? r.deploymentTarget : null,
+        gameApiUrl: typeof r.gameApiUrl === 'string' && r.gameApiUrl ? r.gameApiUrl : null,
+    };
+}
+/**
+ * App discovery & game-api routing — exposed as `client.apps`.
+ *
+ * Targets the **management-api** (every call routes to `managementUrl`), where
+ * the apps catalog lives. After the database split an app may be served by its
+ * own per-tenant cks-game-api; the catalog returns each app's `gameApiUrl` so
+ * you can build a per-app `CrowdyClient` against the correct endpoint (see
+ * {@link routeFor} / {@link AppRoute}).
+ *
+ * Auth: {@link appBySlug} is **public** (no session; resolves unlisted or draft
+ * apps when the exact slugs are known). {@link app}, {@link myApps}, and
+ * {@link routeFor} require authentication (any signed-in user) and otherwise
+ * throw {@link CrowdyGraphQLError} with `UNAUTHENTICATED`; note {@link app} does
+ * not enforce org/app permissions. `BigInt` ids such as `appId` and `orgId` are
+ * decimal strings.
+ *
+ * @example
+ * ```ts
+ * const base = createCrowdyClient({
+ *   managementUrl: 'https://api.example.com',
+ *   httpUrl: 'https://legacy-game-api.example.com', // pre-split fallback
+ * });
+ * await base.auth.login({ email, password });
+ *
+ * const route = await base.apps.routeFor(appId);
+ * if (route.gameApiUrl) {
+ *   // route gameplay to the app's resolved game-api endpoint
+ *   const perAppClient = createCrowdyClient({
+ *     managementUrl: 'https://api.example.com',
+ *     httpUrl: route.gameApiUrl,
+ *     wsUrl: route.gameApiUrl.replace(/^http/, 'ws'),
+ *     tokenStore: base.session.tokenStore,
+ *   });
+ * }
+ * ```
+ */
+export class AppsAPI {
+    constructor(management) {
+        this.management = management;
+    }
+    /**
+     * Fetch a single app by its numeric id. Requires authentication (any signed-in
+     * user); does **not** enforce org/app permissions, so it can read apps the
+     * caller does not own, of any visibility/status. Prefer {@link appBySlug} for
+     * slug-based marketplace lookups.
+     *
+     * @param appId - Numeric id of the app (`BigInt` as a decimal string).
+     * @returns The {@link App}, or `null` if the id does not exist.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` if the caller is not signed in.
+     */
+    async app(appId) {
+        const data = await this.management.request(AppDocument, { appId });
+        return data.app;
+    }
+    /**
+     * Look up a single app by its org slug + app slug (the marketplace URL path).
+     * **Public**: no authentication required, and not filtered by visibility or
+     * status — it can resolve unlisted or draft apps when the exact slugs are
+     * known.
+     *
+     * @param orgSlug - URL slug of the owning organization (e.g. `"acme"` in the
+     *   path `/acme/my-game`).
+     * @param appSlug - URL slug of the app within the org (e.g. `"my-game"`);
+     *   unique per org.
+     * @returns The {@link App}, or `null` if no matching app exists.
+     * @throws {CrowdyGraphQLError} on transport/validation failures.
+     */
+    async appBySlug(orgSlug, appSlug) {
+        const data = await this.management.request(AppBySlugDocument, { orgSlug, appSlug });
+        return data.appBySlug;
+    }
+    /**
+     * List the apps the authenticated caller can see in their account: those owned
+     * by an org they are an active member of, OR those where they hold an active
+     * access grant. Includes apps of any visibility/status (e.g. accessible
+     * drafts), ordered newest-first. Requires authentication.
+     *
+     * @returns The caller's accessible {@link App}s (an empty array if none).
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` if the caller is not signed in.
+     */
+    async myApps() {
+        const data = await this.management.request(MyAppsDocument, {});
+        return data.myApps;
+    }
+    /**
+     * Convenience wrapper over {@link app} that returns just the {@link AppRoute}
+     * routing tuple for an app — i.e. which game-api endpoint should serve it. If
+     * the app row is missing or the API does not expose the split-mode fields yet,
+     * returns a safe default (`{ appId, splitMode: false, deploymentTarget: null,
+     * gameApiUrl: null }`) so the caller keeps using the legacy single-endpoint
+     * deployment.
+     *
+     * @param appId - Numeric id of the app (`BigInt` as a decimal string).
+     * @returns The {@link AppRoute}; route gameplay to `gameApiUrl` when non-null,
+     *   otherwise fall back to the constructor `httpUrl`.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` (it calls {@link app} under
+     *   the hood).
+     */
+    async routeFor(appId) {
+        const row = await this.app(appId);
+        return (appRouteFromAppRow(row) ?? {
+            appId,
+            splitMode: false,
+            deploymentTarget: null,
+            gameApiUrl: null,
+        });
+    }
+    /**
+     * List the apps owned by an organization (by org slug). Studio-admin read —
+     * requires the caller to be a member of the org.
+     *
+     * @param orgSlug - URL slug of the owning organization.
+     * @returns The org's {@link App}s.
+     * @throws {CrowdyGraphQLError} `UNAUTHENTICATED` / `FORBIDDEN`.
+     */
+    async forOrg(orgSlug) {
+        const data = await this.management.request(AppsForOrgDocument, { orgSlug });
+        return data.appsForOrg;
+    }
+    /**
+     * List the public marketplace apps (LIVE + PUBLIC only) with offset
+     * pagination. **Public** — no session required.
+     *
+     * @param opts - Optional {@link AppMarketplaceFilterInput} `filter` and
+     *   `limit` / `offset`.
+     * @returns A page of marketplace apps.
+     * @remarks Prefer {@link marketplaceConnection} (Relay cursor pagination) for
+     *   large catalogs; the offset args here are deprecated server-side.
+     */
+    async marketplace(opts = {}) {
+        const data = await this.management.request(MarketplaceAppsDocument, opts);
+        return data.apps;
+    }
+    /**
+     * Relay-style cursor pagination over the public marketplace — the preferred
+     * alternative to {@link marketplace}. **Public.** See
+     * https://docs.crowdedkingdoms.com/overview/pagination.
+     *
+     * @param args - Optional `first`, `after`, and {@link AppMarketplaceFilterInput}.
+     * @returns An apps connection.
+     */
+    async marketplaceConnection(args = {}) {
+        const data = await this.management.request(AppsConnectionDocument, args);
+        return data.appsConnection;
+    }
+    /**
+     * Create a new app under an organization. Requires the `manage_apps` org
+     * permission. The new app auto-provisions an open-by-default access tier.
+     *
+     * @param input - {@link CreateAppInput}: `orgId`, `name`, `slug`, optional
+     *   `description`/`visibility`/`metadata`.
+     * @returns The created {@link App}.
+     * @throws {CrowdyGraphQLError} `FORBIDDEN`/`SCOPE_MISSING` without
+     *   `manage_apps`, or `BAD_USER_INPUT` (e.g. duplicate slug).
+     */
+    async create(input) {
+        const data = await this.management.request(CreateAppDocument, { input });
+        return data.createApp;
+    }
+    /**
+     * Update an app's mutable fields. Requires the `manage_apps` app permission.
+     *
+     * @param appId - Numeric app id.
+     * @param input - {@link UpdateAppInput} fields to change.
+     * @returns The updated {@link App}.
+     * @throws {CrowdyGraphQLError} `FORBIDDEN`/`SCOPE_MISSING` without
+     *   `manage_apps`.
+     */
+    async update(appId, input) {
+        const data = await this.management.request(UpdateAppDocument, {
+            appId,
+            input,
+        });
+        return data.updateApp;
+    }
+    /**
+     * Archive (soft-delete) an app. Requires the `manage_apps` app permission.
+     *
+     * @param appId - Numeric app id.
+     * @returns The archived app's new status.
+     * @throws {CrowdyGraphQLError} `FORBIDDEN`/`SCOPE_MISSING` without
+     *   `manage_apps`.
+     */
+    async archive(appId) {
+        const data = await this.management.request(ArchiveAppDocument, { appId });
+        return data.archiveApp;
+    }
+    /**
+     * Override an app's marketplace visibility. **Super-admin only.**
+     *
+     * @param appId - Numeric app id.
+     * @param visibility - The new {@link AppVisibility}.
+     * @returns The app's updated visibility.
+     * @throws {CrowdyGraphQLError} `FORBIDDEN` for non-super-admins.
+     */
+    async setVisibility(appId, visibility) {
+        const data = await this.management.request(SetAppVisibilityDocument, {
+            appId,
+            visibility,
+        });
+        return data.setAppVisibility;
+    }
+}