@tinyburg/tinytower-vegas-sdk 0.0.0-stage → 0.1.1

package/src/Endpoints.ts

@@ -0,0 +1,361 @@
+/**
+ * Tiny Tower Vegas (game code `vegas`) NBSync api endpoints.
+ *
+ * Signing: a random `salt` (signed int32) goes in the path, and `hash` is
+ * `md5(<preimage> + <game secret salt>)` with the preimage
+ * `vegas/<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.
+ * - Standard NBSync endpoint set plus get_visits and receive_item.
+ *
+ * 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;
+
+/** @internal */
+export const DeviceNewPlayerEndpoint = HttpApiEndpoint.get("DeviceNewPlayer", "/register/vegas/: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/vegas/: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/vegas/: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/vegas/: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/vegas/: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/vegas/:playerId/:salt/:hash` -> `{ success:"Found",
+ * gifts:[...] }` (NBSyncItemsGetResponse; no `total` on pt).
+ *
+ * @internal
+ */
+export const SocialGetItemsEndpoint = HttpApiEndpoint.get("SocialGetItems", "/get_items/vegas/: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);
+
+/**
+ * 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/vegas/: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
+ * `vegas/<playerId>/<friendId>/<salt><playerAuthKey>`.
+ *
+ * @internal
+ */
+export const SocialPullFriendGameEndpoint = HttpApiEndpoint.get(
+    "SocialPullFriendGame",
+    "/friend/pull_game/vegas/: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 `vegas/<playerId>/<salt><friendId><playerAuthKey>`.
+ *
+ * @internal
+ */
+export const SocialPullFriendMetaEndpoint = HttpApiEndpoint.post(
+    "SocialPullFriendMeta",
+    "/friend/pull_meta/vegas/: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);
+
+/**
+ * VERIFIED path: `/get_visits/vegas/:playerId/:salt/:hash`. Same envelope as get_items.
+ *
+ * @internal
+ */
+export const SocialGetVisitsEndpoint = HttpApiEndpoint.get(
+    "SocialGetVisits",
+    "/get_visits/vegas/: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_visits.required);
+
+/**
+ * Preimage `vegas/<playerId>/<giftId>/<salt><playerAuthKey>`. Response DTO
+ * NBSyncItemsReceiveResponse (success/error/id).
+ *
+ * @internal
+ */
+export const SocialReceiveItemEndpoint = HttpApiEndpoint.get(
+    "SocialReceiveItem",
+    "/receive_item/vegas/:playerId/:giftId/:salt/:hash",
+    {
+        params: { playerId: NimblebitConfig.PlayerIdSchema, giftId: Schema.Int, salt: U32, hash: Schema.String },
+        error: ApiErrors,
+        success: [
+            ErrorResponse,
+            Schema.Struct({ success: Schema.Literal("Received"), id: Schema.optionalKey(Schema.String) }),
+            Schema.Struct({ success: Schema.Literal("NotReceived") }),
+        ],
+    }
+).annotate(OAuthScope.Required, Scopes.Social.write.receive_item.required);
+
+/**
+ * Snapshot list. Vegas exposes `/sync/current_snapshots/` (and a friend variant).
+ * Envelope follows the Tiny Tower snapshot list shape.
+ *
+ * @internal
+ */
+export const SyncRetrieveSnapshotListEndpoint = HttpApiEndpoint.get(
+    "SyncRetrieveSnapshotList",
+    "/sync/current_snapshots/vegas/:playerId/:salt/:hash",
+    {
+        params: { playerId: NimblebitConfig.PlayerIdSchema, salt: U32, hash: Schema.String },
+        error: ApiErrors,
+        success: [
+            ErrorResponse,
+            NotFoundResponse,
+            Schema.Struct({
+                success: Schema.Literal("Found"),
+                saves: Schema.Array(
+                    Schema.Struct({
+                        id: Schema.Int,
+                        created: Schema.Int,
+                        meta: Schema.Record(Schema.String, Schema.Unknown),
+                    })
+                ),
+            }),
+        ],
+    }
+);
+
+/** @internal */
+export const DeviceManagementGroup = HttpApiGroup.make("DeviceManagementGroup")
+    .add(DeviceNewPlayerEndpoint)
+    .add(DevicePlayerDetailsEndpoint)
+    .add(DeviceVerifyDeviceEndpoint);
+
+/** @internal */
+export const SyncManagementGroup = HttpApiGroup.make("SyncManagementGroup")
+    .add(SyncPullSaveEndpoint)
+    .add(SyncCheckForNewerSaveEndpoint)
+    .add(SyncRetrieveSnapshotListEndpoint);
+
+/** @internal */
+export const SocialGroup = HttpApiGroup.make("SocialGroup")
+    .add(SocialGetItemsEndpoint)
+    .add(SocialGetVisitsEndpoint)
+    .add(SocialReceiveItemEndpoint)
+    .add(SocialSendItemEndpoint)
+    .add(SocialPullFriendGameEndpoint)
+    .add(SocialPullFriendMetaEndpoint);
+
+/**
+ * The Tiny Tower Vegas NBSync api.
+ *
+ * @since 1.0.0
+ * @category Api
+ */
+export const Api = HttpApi.make("TinyTowerVegasApi")
+    .add(DeviceManagementGroup)
+    .add(SyncManagementGroup)
+    .add(SocialGroup);

package/src/Scopes.ts

@@ -0,0 +1,90 @@
+/**
+ * The scopes the Tiny Tower Vegas 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 TinyTowerVegas = defineGame({
+    name: "tinytowervegas",
+    description: "Tiny Tower Vegas",
+    read: { description: "Everything in Tiny Tower Vegas that only looks" },
+    write: { description: "Everything in Tiny Tower Vegas 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_visits: "See who has visited 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",
+                    receive_item: "Accept an item on a player's behalf",
+                },
+            },
+        },
+    },
+});
+
+/**
+ * The game's areas, by name, for annotating endpoints.
+ *
+ * @since 1.0.0
+ * @category Areas
+ */
+export const { device: Device, social: Social } = TinyTowerVegas.areas;
+
+/**
+ * @since 1.0.0
+ * @category Tree
+ */
+export const Games: ReadonlyArray<Game> = [TinyTowerVegas];
+
+/**
+ * @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/TinyTowerVegas.ts

@@ -0,0 +1,186 @@
+/**
+ * Tiny Tower Vegas 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 `vegas` 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(`vegas/${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(`vegas/${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(`vegas/${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(`vegas/${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/index.ts

@@ -0,0 +1,58 @@
+/**
+ * @since 1.0.0
+ */
+
+/**
+ * Tiny Tower Vegas (game code `vegas`) NBSync api endpoints.
+ *
+ * Signing: a random `salt` (signed int32) goes in the path, and `hash` is
+ * `md5(<preimage> + <game secret salt>)` with the preimage
+ * `vegas/<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.
+ * - Standard NBSync endpoint set plus get_visits and receive_item.
+ *
+ * Game-specific save/meta schemas are left as `Schema.Unknown` placeholders.
+ *
+ * @since 1.0.0
+ * @category Endpoints
+ */
+export * as Endpoints from "./Endpoints.ts"
+
+/**
+ * The scopes the Tiny Tower Vegas 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"
+
+/**
+ * Tiny Tower Vegas 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 `vegas` 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 TinyTowerVegas from "./TinyTowerVegas.ts"