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

package/src/PocketPlanes.ts

@@ -0,0 +1,264 @@
+/**
+ * Pocket Planes 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 `pp` 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(`pp/${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(`pp/${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(`pp/${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 visits (bitizen/plane exchanges) waiting for the player. VERIFIED.
+ *
+ * @since 1.0.0
+ * @category SDK
+ */
+export const social_getVisits = Effect.fn("social_getVisits")(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: "SocialGetVisits",
+        httpClient: HttpClient.mapRequest(httpClient, maybeAddBearerToken),
+    });
+
+    const salt = yield* nimblebitAuth.salt;
+    const hash = yield* nimblebitAuth.sign(`pp/${playerId}/${salt}${Redacted.value(playerAuthKey)}`);
+    const response = yield* endpoint({ params: { playerId, salt, hash } });
+
+    if ("error" in response) {
+        return yield* new NimblebitError.NimblebitError({
+            method: "SocialGetVisits",
+            module: "SocialGroup",
+            cause: response.error,
+        });
+    }
+    return response;
+});
+
+/**
+ * Lists gifts waiting for the player. VERIFIED.
+ *
+ * @since 1.0.0
+ * @category SDK
+ */
+export const social_getGifts = Effect.fn("social_getGifts")(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: "SocialGetGifts",
+        httpClient: HttpClient.mapRequest(httpClient, maybeAddBearerToken),
+    });
+
+    const salt = yield* nimblebitAuth.salt;
+    const hash = yield* nimblebitAuth.sign(`pp/${playerId}/${salt}${Redacted.value(playerAuthKey)}`);
+    const response = yield* endpoint({ params: { playerId, salt, hash } });
+
+    if ("error" in response) {
+        return yield* new NimblebitError.NimblebitError({
+            method: "SocialGetGifts",
+            module: "SocialGroup",
+            cause: response.error,
+        });
+    }
+    return response;
+});
+
+/**
+ * Lists item requests waiting for the player (Pocket Planes specific;
+ * `{ success, gifts }` with no `total`). VERIFIED.
+ *
+ * @since 1.0.0
+ * @category SDK
+ */
+export const social_requestItems = Effect.fn("social_requestItems")(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: "SocialRequestItems",
+        httpClient: HttpClient.mapRequest(httpClient, maybeAddBearerToken),
+    });
+
+    const salt = yield* nimblebitAuth.salt;
+    const hash = yield* nimblebitAuth.sign(`pp/${playerId}/${salt}${Redacted.value(playerAuthKey)}`);
+    const response = yield* endpoint({ params: { playerId, salt, hash } });
+
+    if ("error" in response) {
+        return yield* new NimblebitError.NimblebitError({
+            method: "SocialRequestItems",
+            module: "SocialGroup",
+            cause: response.error,
+        });
+    }
+    return response;
+});

package/src/Scopes.ts

@@ -0,0 +1,92 @@
+/**
+ * The scopes the Pocket Planes 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 PocketPlanes = defineGame({
+    name: "pocketplanes",
+    description: "Pocket Planes",
+    read: { description: "Everything in Pocket Planes that only looks" },
+    write: { description: "Everything in Pocket Planes 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: {
+                    register_email: "Attach an email address to a player",
+                    verify_device: "Complete a device verification code",
+                },
+            },
+        },
+        social: {
+            description: "Gifts, visits and friends",
+            read: {
+                description: "See gifts, visits and friends' games",
+                leaves: {
+                    get_visits: "See who has visited a player",
+                    get_gifts: "See the gifts waiting for a player",
+                    request_items: "See the item requests waiting for a player",
+                    pull_friend_meta: "Fetch metadata about a player's friends",
+                    pull_friend_game: "Download a friend's game data",
+                },
+            },
+            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 } = PocketPlanes.areas;
+
+/**
+ * @since 1.0.0
+ * @category Tree
+ */
+export const Games: ReadonlyArray<Game> = [PocketPlanes];
+
+/**
+ * @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,72 @@
+/**
+ * @since 1.0.0
+ */
+
+/**
+ * Pocket Planes (game code `pp`) NBSync api endpoints.
+ *
+ * Signing: a random `salt` (signed int32 - the game emits negatives too) goes
+ * in the path, and `hash` is `md5(<preimage> + <game secret salt>)` where the
+ * preimage is `pp/<playerId>/<salt><playerAuthKey>` (variants noted per
+ * endpoint). The secret salt is the value extracted from `NBSync._ss`.
+ *
+ * Verification (against the live server + Frida inspection of the game,
+ * 2026-08-26):
+ * - Signing is MD5, VERIFIED server-side: `player_details` accepts the MD5 hash
+ *   and rejects a garbage hash, no hash, and a SHA-256 hash. (The game itself
+ *   computes SHA-256 in `NBSync.genHash` for the unauthenticated `register`
+ *   call, which the server also accepts via MD5 - so it does not affect the
+ *   authenticated endpoints this SDK signs.)
+ * - Response envelopes VERIFIED by reading the game's DTO classes at runtime
+ *   (immune to the metadata obfuscation): register (NBSyncRegisterResponse),
+ *   player_details (NBSyncPlayerDetailsResponse), sync/pull
+ *   (NBSyncGameSaveResponse: success/h/id/data), current_version
+ *   (NBSyncCurrentCheckResponse), verify_device (NBSyncVerifyCodeResponse:
+ *   success/player_id/player_ss/player_email - no photo/nickname on pp),
+ *   get_visits/get_gifts (NBSyncItemsGetResponse), send_item
+ *   (NBSyncItemsSendResponse), receive_item (NBSyncItemsReceiveResponse: also
+ *   carries an `id`), friend/pull_game (NBSyncFriendGameSaveResponse),
+ *   friend/pull_meta (NBSyncFriendGameMetaResponse). register/player_details/
+ *   get_visits/get_gifts/request_items were also exercised live with a burnbot.
+ * - Still open: pp appears to have NO snapshots (`sync/current_snapshots`
+ *   returns Invalid Request), so `pull_snapshot` here is unconfirmed and may
+ *   not exist. register_email is DERIVED from Tiny Tower.
+ *
+ * Game-specific payload/item schemas (the `gifts` element - real shape is
+ * NBSyncItemsGift {gift_id, gift_to, gift_from, gift_type, item_type, gift_str,
+ * h, c} - friend meta, save push meta) are `Schema.Unknown` placeholders for
+ * the data-schema work.
+ *
+ * @since 1.0.0
+ * @category Endpoints
+ */
+export * as Endpoints from "./Endpoints.ts"
+
+/**
+ * Pocket Planes 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 `pp` 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 PocketPlanes from "./PocketPlanes.ts"
+
+/**
+ * The scopes the Pocket Planes 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"