@tinyburg/pocket-trains-sdk 0.0.0-stage → 0.1.0

package/src/Endpoints.ts

@@ -0,0 +1,325 @@
+/**
+ * Pocket Trains (game code `pt`) NBSync api endpoints.
+ *
+ * Signing: a random `salt` (signed int32) goes in the path, and `hash` is
+ * `md5(<preimage> + <game secret salt>)` with the preimage
+ * `pt/<playerId>/<salt><playerAuthKey>` (variants noted per endpoint). The
+ * secret salt is the value extracted from `NBSync._ss`.
+ *
+ * Verification (live server + Frida DTO inspection of the game, 2026-08-26):
+ * - Signing is MD5, server-validated (same scheme as Tiny Tower / Pocket
+ *   Planes; the game computes SHA-256 only for the unauthenticated `register`).
+ * - Response envelopes VERIFIED by reading the game's DTO classes at runtime:
+ *   register, player_details, sync/pull (NBSyncGameSaveResponse), current_version,
+ *   verify_device, friend/pull_game, friend/pull_meta (meta is a flat
+ *   Dictionary<String,Object> on pt), send_item (NBSyncItemsSendResponse),
+ *   get_items (NBSyncItemsGetResponse: success/gifts, NO `total` unlike pp).
+ *   `get_items` was also exercised live with a burnbot.
+ * - pt-specific gifting: `get_gifts_pt` -> NBSyncGetPTGiftResponse with
+ *   NBSyncGetPTGift elements, plus a gift-id flow (NBSyncGetGiftIDResponse,
+ *   `friend/pull_meta_gift_id`). The get_gifts_pt REQUEST params are UNCONFIRMED
+ *   (the tried `/get_gifts_pt/pt/:playerId/:salt/:hash` form was rejected), so
+ *   that endpoint is marked accordingly.
+ *
+ * Game-specific save/meta schemas are left as `Schema.Unknown` placeholders.
+ *
+ * @since 1.0.0
+ * @category Endpoints
+ */
+
+import { HttpApi, HttpApiEndpoint, HttpApiError, HttpApiGroup } from "effect/http-api";
+import * as Schema from "effect/Schema";
+
+import * as NimblebitConfig from "@tinyburg/nimblebit-sdk/NimblebitConfig";
+import * as OAuthScope from "@yielded/auth/OAuthScope";
+
+import * as Scopes from "./Scopes.ts";
+
+/** @internal */
+export const U32 = Schema.Int.check(Schema.isUint32());
+
+/** @internal */
+export const ApiErrors = [
+    HttpApiError.Forbidden,
+    HttpApiError.BadRequest,
+    HttpApiError.Unauthorized,
+    HttpApiError.InternalServerError,
+] as const;
+
+/** @internal */
+export const ErrorResponse = Schema.Struct({ error: Schema.String });
+
+/** @internal */
+export const NotFoundResponse = Schema.Struct({ success: Schema.Literal("NotFound") });
+
+/** @internal */
+export const SentResponse = Schema.Struct({ success: Schema.Literal("Sent") });
+
+/** @internal */
+export const NotSentResponse = Schema.Struct({ success: Schema.Literal("NotSent") });
+
+/**
+ * A gift/item in the general item channel (get_items / send_item). Verified DTO
+ * NBSyncItemsGift on pt: `{gift_id, gift_to, gift_from, gift_type, item_type,
+ * gift_str, h}` (no `c`, unlike pp). Left open for the data-schema work.
+ *
+ * @since 1.0.0
+ * @category Schemas
+ */
+export const Gift = Schema.Unknown;
+
+/**
+ * A Pocket Trains gift (get_gifts_pt channel). Verified DTO NBSyncGetPTGift:
+ * `{gift_id, gift_to, gift_from, alt_id, gift_type, gift_str: int, gift_quantity:
+ * int, h}`. Left open for the data-schema work.
+ *
+ * @since 1.0.0
+ * @category Schemas
+ */
+export const PTGift = Schema.Unknown;
+
+/** @internal */
+export const DeviceNewPlayerEndpoint = HttpApiEndpoint.get("DeviceNewPlayer", "/register/pt/:salt1/:salt2/:hash", {
+    params: { salt1: U32, salt2: U32, hash: Schema.String },
+    error: ApiErrors,
+    success: [
+        ErrorResponse,
+        Schema.Struct({
+            playerId: NimblebitConfig.PlayerIdSchema,
+            playerSs: NimblebitConfig.PlayerAuthKeySchema,
+        }).pipe(Schema.encodeKeys({ playerId: "player_id", playerSs: "player_ss" })),
+    ],
+});
+
+/** @internal */
+export const DevicePlayerDetailsEndpoint = HttpApiEndpoint.get(
+    "DevicePlayerDetails",
+    "/player_details/pt/:playerId/:salt/:hash",
+    {
+        params: { playerId: NimblebitConfig.PlayerIdSchema, salt: U32, hash: Schema.String },
+        error: ApiErrors,
+        success: [
+            ErrorResponse,
+            Schema.Struct({
+                success: Schema.Literal("Found"),
+                player: Schema.Struct({
+                    playerId: NimblebitConfig.PlayerIdSchema,
+                    playerEmail: NimblebitConfig.PlayerEmailSchema,
+                    registered: Schema.NumberFromString.pipe(Schema.decodeTo(Schema.BooleanFromBit)),
+                    blacklisted: Schema.NumberFromString.pipe(Schema.decodeTo(Schema.BooleanFromBit)),
+                    saveVersion: Schema.NumberFromString.pipe(Schema.decodeTo(Schema.Int)),
+                    checksum: Schema.String,
+                }).pipe(Schema.encodeKeys({ playerId: "player_id", playerEmail: "email", checksum: "h" })),
+            }),
+        ],
+    }
+).annotate(OAuthScope.Required, Scopes.Device.read.player_details.required);
+
+/** @internal */
+export const DeviceVerifyDeviceEndpoint = HttpApiEndpoint.get(
+    "DeviceVerifyDevice",
+    "/verify_device/pt/:playerId/:verificationCode",
+    {
+        params: { playerId: NimblebitConfig.PlayerIdSchema, verificationCode: Schema.String },
+        error: ApiErrors,
+        success: [
+            ErrorResponse,
+            Schema.Struct({
+                success: Schema.Literal("NewDevice"),
+                playerId: NimblebitConfig.PlayerIdSchema,
+                playerAuthKey: NimblebitConfig.PlayerAuthKeySchema,
+                playerEmail: NimblebitConfig.PlayerEmailSchema,
+            }).pipe(
+                Schema.encodeKeys({ playerId: "player_id", playerAuthKey: "player_ss", playerEmail: "player_email" })
+            ),
+        ],
+    }
+).annotate(OAuthScope.Required, Scopes.Device.write.verify_device.required);
+
+/**
+ * Pull the player's cloud save. VERIFIED envelope (NBSyncGameSaveResponse). No-save
+ * case returns `{ error: "SaveNotFound" }`. `data` is base64 pako-deflated bytes.
+ *
+ * @internal
+ */
+export const SyncPullSaveEndpoint = HttpApiEndpoint.get("SyncPullSave", "/sync/pull/pt/:playerId/:salt/:hash", {
+    params: { playerId: NimblebitConfig.PlayerIdSchema, salt: U32, hash: Schema.String },
+    error: ApiErrors,
+    success: [
+        ErrorResponse,
+        NotFoundResponse,
+        Schema.Struct({
+            success: Schema.Literal("Found"),
+            data: Schema.Uint8ArrayFromBase64,
+            checksum: Schema.String,
+            saveId: Schema.NumberFromString,
+        }).pipe(Schema.encodeKeys({ checksum: "h", saveId: "id" })),
+    ],
+});
+
+/**
+ * VERIFIED envelope (NBSyncCurrentCheckResponse); no-save returns `{ error: "NoSave" }`.
+ *
+ * @internal
+ */
+export const SyncCheckForNewerSaveEndpoint = HttpApiEndpoint.get(
+    "SyncCheckForNewerSave",
+    "/sync/current_version/pt/:playerId/:salt/:hash",
+    {
+        params: { playerId: NimblebitConfig.PlayerIdSchema, salt: U32, hash: Schema.String },
+        error: ApiErrors,
+        success: [
+            ErrorResponse,
+            NotFoundResponse,
+            Schema.Struct({
+                success: Schema.Literal("Found"),
+                checksum: Schema.String,
+                saveId: Schema.NumberFromString,
+            }).pipe(Schema.encodeKeys({ checksum: "h", saveId: "id" })),
+        ],
+    }
+);
+
+/**
+ * VERIFIED live: `/get_items/pt/:playerId/:salt/:hash` -> `{ success:"Found",
+ * gifts:[...] }` (NBSyncItemsGetResponse; no `total` on pt).
+ *
+ * @internal
+ */
+export const SocialGetItemsEndpoint = HttpApiEndpoint.get("SocialGetItems", "/get_items/pt/:playerId/:salt/:hash", {
+    params: { playerId: NimblebitConfig.PlayerIdSchema, salt: U32, hash: Schema.String },
+    error: ApiErrors,
+    success: [
+        ErrorResponse,
+        NotFoundResponse,
+        Schema.Struct({ success: Schema.Literal("Found"), gifts: Schema.Array(Gift) }),
+    ],
+}).annotate(OAuthScope.Required, Scopes.Social.read.get_items.required);
+
+/**
+ * Pocket Trains gift channel. Response VERIFIED (NBSyncGetPTGiftResponse) but the
+ * REQUEST params are UNCONFIRMED - the `/get_gifts_pt/pt/:playerId/:salt/:hash`
+ * form was rejected with "Invalid Request", so pt's gift request likely needs a
+ * gift-id (see NBSyncGetGiftIDResponse / `friend/pull_meta_gift_id`). Path/params
+ * below are a placeholder to be confirmed by capturing the live request.
+ *
+ * @internal
+ */
+export const SocialGetGiftsPtEndpoint = HttpApiEndpoint.get(
+    "SocialGetGiftsPt",
+    "/get_gifts_pt/pt/:playerId/:salt/:hash",
+    {
+        params: { playerId: NimblebitConfig.PlayerIdSchema, salt: U32, hash: Schema.String },
+        error: ApiErrors,
+        success: [
+            ErrorResponse,
+            NotFoundResponse,
+            Schema.Struct({ success: Schema.Literal("Found"), gifts: Schema.Array(PTGift) }),
+        ],
+    }
+).annotate(OAuthScope.Required, Scopes.Social.read.get_gifts_pt.required);
+
+/**
+ * DERIVED from Tiny Tower. Sends an item to a friend. Response VERIFIED
+ * (NBSyncItemsSendResponse: success/error). pt also has a `/send_pt/` variant.
+ *
+ * @internal
+ */
+export const SocialSendItemEndpoint = HttpApiEndpoint.post(
+    "SocialSendItem",
+    "/send_item/pt/:itemType/:playerId/:friendId/:salt/:hash",
+    {
+        params: {
+            itemType: Schema.String,
+            playerId: NimblebitConfig.PlayerIdSchema,
+            friendId: NimblebitConfig.PlayerIdSchema,
+            salt: U32,
+            hash: Schema.String,
+        },
+        payload: Schema.Struct({ itemStr: Schema.String }),
+        error: ApiErrors,
+        success: [ErrorResponse, SentResponse, NotSentResponse],
+    }
+).annotate(OAuthScope.Required, Scopes.Social.write.send_item.required);
+
+/**
+ * VERIFIED envelope (NBSyncFriendGameSaveResponse); preimage
+ * `pt/<playerId>/<friendId>/<salt><playerAuthKey>`.
+ *
+ * @internal
+ */
+export const SocialPullFriendGameEndpoint = HttpApiEndpoint.get(
+    "SocialPullFriendGame",
+    "/friend/pull_game/pt/:playerId/:friendId/:salt/:hash",
+    {
+        params: {
+            playerId: NimblebitConfig.PlayerIdSchema,
+            friendId: NimblebitConfig.PlayerIdSchema,
+            salt: U32,
+            hash: Schema.String,
+        },
+        error: ApiErrors,
+        success: [
+            ErrorResponse,
+            NotFoundResponse,
+            Schema.Struct({
+                success: Schema.Literal("Found"),
+                data: Schema.Uint8ArrayFromBase64,
+                checksum: Schema.String,
+                saveId: Schema.NumberFromString,
+                playerId: NimblebitConfig.PlayerIdSchema,
+            }).pipe(Schema.encodeKeys({ checksum: "h", saveId: "id", playerId: "player_id" })),
+        ],
+    }
+).annotate(OAuthScope.Required, Scopes.Social.read.pull_friend_game.required);
+
+/**
+ * VERIFIED envelope (NBSyncFriendGameMetaResponse; `meta` is a flat
+ * Dictionary<String,Object> on pt). Preimage `pt/<playerId>/<salt><friendId><playerAuthKey>`.
+ *
+ * @internal
+ */
+export const SocialPullFriendMetaEndpoint = HttpApiEndpoint.post(
+    "SocialPullFriendMeta",
+    "/friend/pull_meta/pt/:playerId/:salt/:hash",
+    {
+        params: { playerId: NimblebitConfig.PlayerIdSchema, salt: U32, hash: Schema.String },
+        payload: Schema.Struct({ friends: NimblebitConfig.PlayerIdSchema }),
+        error: ApiErrors,
+        success: [
+            ErrorResponse,
+            NotFoundResponse,
+            Schema.Struct({
+                success: Schema.Literal("Found"),
+                meta: Schema.Record(NimblebitConfig.PlayerIdSchema, Schema.Unknown),
+            }),
+        ],
+    }
+).annotate(OAuthScope.Required, Scopes.Social.read.pull_friend_meta.required);
+
+/** @internal */
+export const DeviceManagementGroup = HttpApiGroup.make("DeviceManagementGroup")
+    .add(DeviceNewPlayerEndpoint)
+    .add(DevicePlayerDetailsEndpoint)
+    .add(DeviceVerifyDeviceEndpoint);
+
+/** @internal */
+export const SyncManagementGroup = HttpApiGroup.make("SyncManagementGroup")
+    .add(SyncPullSaveEndpoint)
+    .add(SyncCheckForNewerSaveEndpoint);
+
+/** @internal */
+export const SocialGroup = HttpApiGroup.make("SocialGroup")
+    .add(SocialGetItemsEndpoint)
+    .add(SocialGetGiftsPtEndpoint)
+    .add(SocialSendItemEndpoint)
+    .add(SocialPullFriendGameEndpoint)
+    .add(SocialPullFriendMetaEndpoint);
+
+/**
+ * The Pocket Trains NBSync api.
+ *
+ * @since 1.0.0
+ * @category Api
+ */
+export const Api = HttpApi.make("PocketTrainsApi").add(DeviceManagementGroup).add(SyncManagementGroup).add(SocialGroup);

package/src/PocketTrains.ts

@@ -0,0 +1,186 @@
+/**
+ * Pocket Trains SDK: signed calls against Nimblebit's NBSync service.
+ *
+ * Signing reuses `@tinyburg/nimblebit-sdk` (`NimblebitAuth`): the game secret
+ * salt (from `NBSync._ss`) is provided as the auth key, and each request is
+ * `md5(<preimage> + <secret salt>)` with a random uint32 `salt` in the path.
+ * All method preimages below are the Tiny Tower formula with the `pt` game code.
+ *
+ * The methods that were exercised live against sync.nimblebit.com are marked
+ * VERIFIED; save-bearing / write paths follow the same pattern but were not
+ * exercised. Save bytes are returned raw (base64-decoded); inflating (pako) and
+ * parsing into a save schema is left to the caller.
+ *
+ * @since 1.0.0
+ * @category SDK
+ */
+
+import type * as Schema from "effect/Schema";
+
+import * as Effect from "effect/Effect";
+import * as Function from "effect/Function";
+import { HttpClient, HttpClientRequest } from "effect/http";
+import { HttpApiClient } from "effect/http-api";
+import * as Redacted from "effect/Redacted";
+
+import type { NimblebitConfig } from "@tinyburg/nimblebit-sdk";
+
+import { NimblebitAuth, NimblebitError } from "@tinyburg/nimblebit-sdk";
+
+import * as Endpoints from "./Endpoints.ts";
+
+/**
+ * Requests a new player ("burnbot") from the Nimblebit servers. VERIFIED.
+ *
+ * @since 1.0.0
+ * @category SDK
+ */
+export const device_newPlayer = Effect.gen(function* () {
+    const nimblebitAuth = yield* NimblebitAuth.NimblebitAuth;
+    const httpClient = yield* HttpClient.HttpClient;
+
+    const maybeAddBearerToken =
+        nimblebitAuth.host !== "https://sync.nimblebit.com"
+            ? HttpClientRequest.bearerToken(nimblebitAuth.authKey)
+            : Function.identity;
+
+    const endpoint = yield* HttpApiClient.endpoint(Endpoints.Api, {
+        baseUrl: nimblebitAuth.host,
+        group: "DeviceManagementGroup",
+        endpoint: "DeviceNewPlayer",
+        httpClient: HttpClient.mapRequest(httpClient, maybeAddBearerToken),
+    });
+
+    const salt1 = yield* nimblebitAuth.salt;
+    const salt2 = yield* nimblebitAuth.salt;
+    const hash = yield* nimblebitAuth.sign(`pt/${salt1}/${salt2}`);
+    const response = yield* endpoint({ params: { salt1, salt2, hash } });
+
+    if ("error" in response) {
+        return yield* new NimblebitError.NimblebitError({
+            method: "DeviceNewPlayer",
+            module: "DeviceManagementGroup",
+            cause: response.error,
+        });
+    }
+    return response;
+});
+
+/**
+ * Retrieves player details. VERIFIED.
+ *
+ * @since 1.0.0
+ * @category SDK
+ */
+export const device_playerDetails = Effect.fn("device_playerDetails")(function* ({
+    playerAuthKey,
+    playerId,
+}: Schema.Schema.Type<typeof NimblebitConfig.AuthenticatedPlayerSchema>) {
+    const nimblebitAuth = yield* NimblebitAuth.NimblebitAuth;
+    const httpClient = yield* HttpClient.HttpClient;
+
+    const maybeAddBearerToken =
+        nimblebitAuth.host !== "https://sync.nimblebit.com"
+            ? HttpClientRequest.bearerToken(nimblebitAuth.authKey)
+            : Function.identity;
+
+    const endpoint = yield* HttpApiClient.endpoint(Endpoints.Api, {
+        baseUrl: nimblebitAuth.host,
+        group: "DeviceManagementGroup",
+        endpoint: "DevicePlayerDetails",
+        httpClient: HttpClient.mapRequest(httpClient, maybeAddBearerToken),
+    });
+
+    const salt = yield* nimblebitAuth.salt;
+    const hash = yield* nimblebitAuth.sign(`pt/${playerId}/${salt}${Redacted.value(playerAuthKey)}`);
+    const response = yield* endpoint({ params: { playerId, salt, hash } });
+
+    if ("error" in response) {
+        return yield* new NimblebitError.NimblebitError({
+            method: "DevicePlayerDetails",
+            module: "DeviceManagementGroup",
+            cause: response.error,
+        });
+    }
+    return response.player;
+});
+
+/**
+ * Pulls the player's cloud save. Returns raw base64-decoded bytes (inflate +
+ * parse separately). Success envelope DERIVED from Tiny Tower.
+ *
+ * @since 1.0.0
+ * @category SDK
+ */
+export const sync_pullSave = Effect.fn("sync_pullSave")(function* ({
+    playerAuthKey,
+    playerId,
+}: Schema.Schema.Type<typeof NimblebitConfig.AuthenticatedPlayerSchema>) {
+    const nimblebitAuth = yield* NimblebitAuth.NimblebitAuth;
+    const httpClient = yield* HttpClient.HttpClient;
+
+    const maybeAddBearerToken =
+        nimblebitAuth.host !== "https://sync.nimblebit.com"
+            ? HttpClientRequest.bearerToken(nimblebitAuth.authKey)
+            : Function.identity;
+
+    const endpoint = yield* HttpApiClient.endpoint(Endpoints.Api, {
+        baseUrl: nimblebitAuth.host,
+        group: "SyncManagementGroup",
+        endpoint: "SyncPullSave",
+        httpClient: HttpClient.mapRequest(httpClient, maybeAddBearerToken),
+    });
+
+    const salt = yield* nimblebitAuth.salt;
+    const hash = yield* nimblebitAuth.sign(`pt/${playerId}/${salt}${Redacted.value(playerAuthKey)}`);
+    const response = yield* endpoint({ params: { playerId, salt, hash } });
+
+    if ("error" in response) {
+        return yield* new NimblebitError.NimblebitError({
+            method: "SyncPullSave",
+            module: "SyncManagementGroup",
+            cause: response.error,
+        });
+    }
+    return response;
+});
+
+/**
+ * Lists items (parts/gifts) waiting for the player. VERIFIED
+ * (`/get_items/pt/...` -> `{ success:"Found", gifts:[...] }`, no total).
+ *
+ * @since 1.0.0
+ * @category SDK
+ */
+export const social_getItems = Effect.fn("social_getItems")(function* ({
+    playerAuthKey,
+    playerId,
+}: Schema.Schema.Type<typeof NimblebitConfig.AuthenticatedPlayerSchema>) {
+    const nimblebitAuth = yield* NimblebitAuth.NimblebitAuth;
+    const httpClient = yield* HttpClient.HttpClient;
+
+    const maybeAddBearerToken =
+        nimblebitAuth.host !== "https://sync.nimblebit.com"
+            ? HttpClientRequest.bearerToken(nimblebitAuth.authKey)
+            : Function.identity;
+
+    const endpoint = yield* HttpApiClient.endpoint(Endpoints.Api, {
+        baseUrl: nimblebitAuth.host,
+        group: "SocialGroup",
+        endpoint: "SocialGetItems",
+        httpClient: HttpClient.mapRequest(httpClient, maybeAddBearerToken),
+    });
+
+    const salt = yield* nimblebitAuth.salt;
+    const hash = yield* nimblebitAuth.sign(`pt/${playerId}/${salt}${Redacted.value(playerAuthKey)}`);
+    const response = yield* endpoint({ params: { playerId, salt, hash } });
+
+    if ("error" in response) {
+        return yield* new NimblebitError.NimblebitError({
+            method: "SocialGetItems",
+            module: "SocialGroup",
+            cause: response.error,
+        });
+    }
+    return response;
+});

package/src/Scopes.ts

@@ -0,0 +1,89 @@
+/**
+ * The scopes the Pocket Trains api is guarded by, as a game-rooted tree, built with
+ * `@tinyburg/nimblebit-sdk`'s `defineGame`. Only the endpoints this sdk defines
+ * are covered; areas without both a read and a write side are left out until
+ * their endpoints exist.
+ *
+ * @since 1.0.0
+ * @category Scopes
+ */
+
+import { type Game, type ScopeDescription, defineGame } from "@tinyburg/nimblebit-sdk/NimblebitScopes";
+
+/**
+ * @since 1.0.0
+ * @category Games
+ */
+export const PocketTrains = defineGame({
+    name: "pockettrains",
+    description: "Pocket Trains",
+    read: { description: "Everything in Pocket Trains that only looks" },
+    write: { description: "Everything in Pocket Trains that changes a player's game" },
+    areas: {
+        device: {
+            description: "Player accounts and their devices",
+            read: {
+                description: "Look up player accounts",
+                leaves: {
+                    player_details: "Look up a player's public profile details",
+                },
+            },
+            write: {
+                description: "Change a player's account or devices",
+                leaves: {
+                    verify_device: "Complete a device verification code",
+                },
+            },
+        },
+        social: {
+            description: "Gifts, visits and friends",
+            read: {
+                description: "See gifts, visits and friends' games",
+                leaves: {
+                    get_items: "See the items waiting for a player",
+                    get_gifts_pt: "See the gifts waiting for a player",
+                    pull_friend_game: "Download a friend's game data",
+                    pull_friend_meta: "Fetch metadata about a player's friends",
+                },
+            },
+            write: {
+                description: "Send and accept gifts and items",
+                leaves: {
+                    send_item: "Send items to another player",
+                },
+            },
+        },
+    },
+});
+
+/**
+ * The game's areas, by name, for annotating endpoints.
+ *
+ * @since 1.0.0
+ * @category Areas
+ */
+export const { device: Device, social: Social } = PocketTrains.areas;
+
+/**
+ * @since 1.0.0
+ * @category Tree
+ */
+export const Games: ReadonlyArray<Game> = [PocketTrains];
+
+/**
+ * @since 1.0.0
+ * @category Tree
+ */
+export const all = (): ReadonlyArray<ScopeDescription> =>
+    Games.flatMap((game) => [
+        game,
+        game.read,
+        game.write,
+        ...Object.values(game.areas).flatMap((area) => [
+            area,
+            area.read,
+            ...area.read.children,
+            area.write,
+            ...area.write.children,
+        ]),
+    ]);

package/src/index.ts

@@ -0,0 +1,62 @@
+/**
+ * @since 1.0.0
+ */
+
+/**
+ * Pocket Trains (game code `pt`) NBSync api endpoints.
+ *
+ * Signing: a random `salt` (signed int32) goes in the path, and `hash` is
+ * `md5(<preimage> + <game secret salt>)` with the preimage
+ * `pt/<playerId>/<salt><playerAuthKey>` (variants noted per endpoint). The
+ * secret salt is the value extracted from `NBSync._ss`.
+ *
+ * Verification (live server + Frida DTO inspection of the game, 2026-08-26):
+ * - Signing is MD5, server-validated (same scheme as Tiny Tower / Pocket
+ *   Planes; the game computes SHA-256 only for the unauthenticated `register`).
+ * - Response envelopes VERIFIED by reading the game's DTO classes at runtime:
+ *   register, player_details, sync/pull (NBSyncGameSaveResponse), current_version,
+ *   verify_device, friend/pull_game, friend/pull_meta (meta is a flat
+ *   Dictionary<String,Object> on pt), send_item (NBSyncItemsSendResponse),
+ *   get_items (NBSyncItemsGetResponse: success/gifts, NO `total` unlike pp).
+ *   `get_items` was also exercised live with a burnbot.
+ * - pt-specific gifting: `get_gifts_pt` -> NBSyncGetPTGiftResponse with
+ *   NBSyncGetPTGift elements, plus a gift-id flow (NBSyncGetGiftIDResponse,
+ *   `friend/pull_meta_gift_id`). The get_gifts_pt REQUEST params are UNCONFIRMED
+ *   (the tried `/get_gifts_pt/pt/:playerId/:salt/:hash` form was rejected), so
+ *   that endpoint is marked accordingly.
+ *
+ * Game-specific save/meta schemas are left as `Schema.Unknown` placeholders.
+ *
+ * @since 1.0.0
+ * @category Endpoints
+ */
+export * as Endpoints from "./Endpoints.ts"
+
+/**
+ * Pocket Trains SDK: signed calls against Nimblebit's NBSync service.
+ *
+ * Signing reuses `@tinyburg/nimblebit-sdk` (`NimblebitAuth`): the game secret
+ * salt (from `NBSync._ss`) is provided as the auth key, and each request is
+ * `md5(<preimage> + <secret salt>)` with a random uint32 `salt` in the path.
+ * All method preimages below are the Tiny Tower formula with the `pt` game code.
+ *
+ * The methods that were exercised live against sync.nimblebit.com are marked
+ * VERIFIED; save-bearing / write paths follow the same pattern but were not
+ * exercised. Save bytes are returned raw (base64-decoded); inflating (pako) and
+ * parsing into a save schema is left to the caller.
+ *
+ * @since 1.0.0
+ * @category SDK
+ */
+export * as PocketTrains from "./PocketTrains.ts"
+
+/**
+ * The scopes the Pocket Trains api is guarded by, as a game-rooted tree, built with
+ * `@tinyburg/nimblebit-sdk`'s `defineGame`. Only the endpoints this sdk defines
+ * are covered; areas without both a read and a write side are left out until
+ * their endpoints exist.
+ *
+ * @since 1.0.0
+ * @category Scopes
+ */
+export * as Scopes from "./Scopes.ts"