macbid-ts-api 1.0.0-beta.4 → 1.1.0-beta.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "macbid-ts-api",
-    "version": "1.0.0-beta.4",
+    "version": "1.1.0-beta.0",
     "repository": {
         "type": "git",
         "url": "git+https://github.com/pkmnct/macbid-ts-api.git"
@@ -17,35 +17,16 @@
         "node": ">=16.0.0"
     },
     "devDependencies": {
-        "@types/node-fetch": "^2.6.2",
-        "@typescript-eslint/eslint-plugin": "^5.61.0",
-        "@typescript-eslint/parser": "^5.61.0",
-        "eslint": "^8.44.0",
-        "eslint-plugin-import": "^2.27.5",
-        "eslint-plugin-promise": "^6.1.1",
-        "typescript": "^5.2.2"
-    },
-    "eslintConfig": {
-        "parser": "@typescript-eslint/parser",
-        "parserOptions": {
-            "ecmaVersion": 2021,
-            "sourceType": "module"
-        },
-        "extends": [
-            "eslint:recommended",
-            "plugin:@typescript-eslint/recommended",
-            "plugin:promise/recommended",
-            "plugin:import/recommended",
-            "plugin:import/typescript"
-        ],
-        "plugins": [
-            "@typescript-eslint",
-            "promise",
-            "import"
-        ]
+        "@eslint/js": "^10.0.1",
+        "@types/node-fetch": "^2.6.13",
+        "eslint": "^10.5.0",
+        "eslint-plugin-promise": "^7.3.0",
+        "typescript": "^6.0.3",
+        "typescript-eslint": "^8.61.1"
     },
     "scripts": {
         "build": "tsc",
+        "lint": "eslint .",
         "prepublish": "npm run build"
     },
     "type": "module",

package/readme.md

@@ -1 +1,86 @@
-# Mac.Bid Typescript API
+# macbid-ts-api
+
+Unofficial TypeScript client for the [Mac.Bid](https://www.mac.bid) API.
+
+## Requirements
+
+Node.js **>= 16**
+
+## Install
+
+```bash
+npm install macbid-ts-api
+```
+
+## Usage
+
+```typescript
+import MacBid, { type SerializableAuthState } from "macbid-ts-api";
+
+const api = new MacBid();
+let state: SerializableAuthState = {};
+
+state = await api.authenticate({
+  email: "you@example.com",
+  password: "your-password",
+  ...state,
+});
+
+const watchlist = await api.get_watchlist();
+```
+
+`authenticate()` returns persistable state (tokens and `device_id`, never credentials). Pass it back in on the next call with `...state`.
+
+### Two-factor authentication
+
+If SMS verification is required, the first call throws after sending a code. Set `state` from `api.getAuthState()` and call again with the code:
+
+```typescript
+let state: SerializableAuthState = {};
+
+try {
+  state = await api.authenticate({ email, password, ...state });
+} catch {
+  state = api.getAuthState();
+}
+
+// User receives SMS, then retry:
+state = await api.authenticate({
+  email,
+  password,
+  validation_code: "123456",
+  ...state,
+});
+```
+
+If `device_id` is set but there are no tokens and no `validation_code`, a code was already sent and a new SMS will not be requested.
+
+For JSON storage, use `MacBid.serializeAuthState` / `MacBid.parseAuthState`.
+
+`AuthInfo` is the type for `authenticate()` params (credentials, `validation_code`, etc.). `SerializableAuthState` is what comes back — safe to persist.
+
+## API
+
+| Method | Description |
+|---|---|
+| `authenticate(params?)` | Log in or refresh session; returns persistable state |
+| `get_watchlist()` | Active watchlist items |
+| `get_active()` | Active won items (e.g. awaiting pickup) |
+| `get_buildings()` | Warehouse buildings |
+| `get_locations()` | Pickup locations |
+| `get(path)` / `post(path, options?)` | Authenticated API requests |
+| `refreshToken()` | Refresh the access token |
+| `getAuthState()` | Current persistable state |
+| `get_refresh_token_expiration()` | Refresh token expiry |
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run lint
+```
+
+## License
+
+MIT

package/MacBid.ts

@@ -1,423 +0,0 @@
-import fetch, { Response } from "node-fetch";
-import { promises as fs } from "node:fs";
-
-export interface AuthInfo {
-  email?: string;
-  password?: string;
-  token?: string;
-  token_expiration?: Date;
-  user_id?: string;
-  refresh_token?: string;
-  refresh_token_expiration?: Date;
-  validation_code?: string;
-  device_id?: string;
-}
-
-export interface WatchlistFull {
-  auction_lot_id: number;
-  watchlist_date_created: Date;
-  id: number;
-  auction_id: number;
-  closed_date: null;
-  buyers_assurance_cost: number | null;
-  expected_close_date: Date;
-  inventory_id: number;
-  date_created: Date;
-  lot_number: string;
-  listing_url: null;
-  title: string;
-  is_open: number;
-  is_transferrable: number;
-  total_bids: number;
-  winning_customer_id: null;
-  winning_bid_id: null;
-  winning_bid_amount: number | null;
-  unique_bidders: number;
-  product_name: string;
-  quantity: number;
-  is_pallet: number;
-  shipping_height: number | null;
-  shipping_width: number | null;
-  shipping_length: number | null;
-  warehouse_location: string;
-  shipping_weight: number | null;
-  case_packed_qty: number | null;
-  auction_number: string;
-  retail_price: number;
-  condition_name: ConditionName;
-  category: null | string;
-  image_url: string;
-  auction_type: AuctionType;
-}
-
-export enum AuctionType {
-  Pallet = "pallet",
-  Standard = "standard",
-}
-
-export enum ConditionName {
-  Damaged = "DAMAGED",
-  LikeNew = "LIKE NEW",
-  OpenBox = "OPEN BOX",
-}
-
-export interface MacBidApiResponse extends Response {
-  json: () => Promise<{
-    [key: string]: unknown;
-  }>;
-}
-
-export class MacBid {
-  public LOGIN_PAGE_URL = "https://www.mac.bid";
-  public API_ROOT = "https://api.macdiscount.com";
-
-  private macbid_session_headers: { [key: string]: string } = {
-    "Content-Type": "application/json",
-  };
-  private auth_info: AuthInfo;
-  private tokenFilePath?: string;
-
-  constructor(auth_info: AuthInfo, tokenFilePath?: string) {
-    this.auth_info = auth_info;
-    this.tokenFilePath = tokenFilePath;
-    // Don't authenticate in constructor - wait until actually needed
-  }
-
-  public authenticate = async () => {
-    if (this.auth_info) {
-      // If we have a token, use it (will be auto-refreshed if expired)
-      if (this.auth_info.token) {
-        this.macbid_session_headers["Authorization"] = this.auth_info
-          .token as string;
-        console.log("Using existing access token");
-        // Token will be auto-refreshed by ensureValidToken if needed
-        return;
-      }
-      
-      // If we have a refresh token but no access token, try to refresh first
-      if (this.auth_info.refresh_token) {
-        if (this.isRefreshTokenExpired()) {
-          console.log("Refresh token has expired, need to login");
-        } else {
-          console.log("No access token, attempting to refresh using refresh token");
-          try {
-            await this.refreshToken();
-            console.log("Successfully refreshed token");
-            return;
-          } catch (error) {
-            // If refresh fails, fall through to login
-            console.warn("Failed to refresh token, attempting login:", error);
-          }
-        }
-      }
-      
-      // No valid tokens, need to login
-      if (this.auth_info.email && this.auth_info.password) {
-        console.log("No valid tokens found, attempting login");
-        await this.login(this.auth_info.email, this.auth_info.password);
-      } else {
-        throw new Error("Invalid auth_info");
-      }
-    }
-  };
-
-  public get = async (path: string): Promise<MacBidApiResponse> => {
-    await this.ensureValidToken();
-    return (await fetch(this.API_ROOT + path, {
-      headers: this.macbid_session_headers,
-    })) as MacBidApiResponse;
-  };
-
-  public post = async (
-    path: string,
-    options?: RequestInit
-  ): Promise<MacBidApiResponse> => {
-    // Don't refresh token for auth endpoints
-    if (!path.includes("/auth/")) {
-      await this.ensureValidToken();
-    }
-    return (await fetch(this.API_ROOT + path, {
-      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-      // @ts-ignore
-      headers: this.macbid_session_headers,
-      method: "POST",
-      ...options,
-    })) as MacBidApiResponse;
-  };
-
-  /**
-   * Raise an exception if an endpoint requiring login is called without valid auth
-   */
-  private check_auth = (): boolean => {
-    if (!this.macbid_session_headers["Authorization"]) {
-      throw new Error("Not authenticated");
-    }
-    return true;
-  };
-
-  /**
-   * Do the login request
-   * @param email - User email
-   * @param password - User password
-   * @param validation_code - Optional validation code. If not provided, will check auth_info.validation_code
-   */
-  public login = async (
-    email: string,
-    password: string,
-    validation_code?: string
-  ): Promise<boolean> => {
-    // Use existing device_id if available, otherwise generate a new one
-    const device_id = this.auth_info.device_id || crypto.randomUUID();
-    if (!this.auth_info.device_id) {
-      this.auth_info.device_id = device_id;
-    }
-
-    const login_params = {
-      device_id: device_id,
-      email: email,
-      password: password,
-      ref_code: null,
-      ref_r: null,
-      remember_me: true,
-      utm_campaign: null,
-      utm_medium: null,
-      utm_source: null,
-    };
-    // https://api.macdiscount.com/auth/auth-validation
-    const res = await this.post("/auth/auth-validation", {
-      body: JSON.stringify(login_params),
-    });
-
-    const resJson = await res.json();
-
-    if (resJson["message"] === "Login validation code sent") {
-      // Get validation code from parameter, auth_info, or throw error
-      const code =
-        validation_code ||
-        this.auth_info.validation_code ||
-        process.env.MACBID_VALIDATION_CODE;
-
-      if (!code) {
-        throw new Error(
-          "Validation code required. Provide it via:\n" +
-            "  1. login() method parameter: login(email, password, validation_code)\n" +
-            "  2. AuthInfo.validation_code when creating MacBid instance\n" +
-            "  3. MACBID_VALIDATION_CODE environment variable"
-        );
-      }
-
-      const validation_params = {
-        code: code,
-        device_id: login_params.device_id,
-        new_password: "",
-        remember_me: true,
-      };
-
-      const validation_res = await this.post("/auth/validate-access-code", {
-        body: JSON.stringify(validation_params),
-      });
-
-      const validation_resJson = await validation_res.json();
-
-      // Check if validation failed
-      if (validation_res.status !== 200 || validation_resJson["error"]) {
-        console.error("Validation failed:", JSON.stringify(validation_resJson, null, 2));
-        throw new Error(`Validation failed: ${validation_resJson["error"] || validation_resJson["message"] || "Unknown error"}`);
-      }
-
-      const access_token = validation_resJson["access_token"] as string;
-      const refresh_token = validation_resJson["refresh_token"] as string;
-      const user_id = validation_resJson["user_id"] as string;
-      const expires = validation_resJson["expires"] as number;
-      const expiration_refresh = validation_resJson["expiration_refresh"] as number;
-
-      if (access_token) {
-        this.auth_info.token = access_token as string;
-        this.auth_info.user_id = user_id as string;
-        this.macbid_session_headers["Authorization"] = this.auth_info.token;
-        this.auth_info.token_expiration = new Date(expires * 1000);
-        this.auth_info.refresh_token = refresh_token;
-        this.auth_info.refresh_token_expiration = new Date(expiration_refresh * 1000);
-        await this.saveTokens();
-        console.log("Login successful, tokens saved");
-        return true;
-      } else {
-        console.error("No access token in validation response:", JSON.stringify(validation_resJson, null, 2));
-        throw new Error("Login failed: No access token received");
-      }
-    }
-    console.error("Unexpected login response:", JSON.stringify(resJson, null, 2));
-    throw new Error("Login failed");
-  };
-
-  public get_refresh_token_expiration = (): Date => {
-    if (this.auth_info.refresh_token_expiration) {
-      return this.auth_info.refresh_token_expiration;
-    } else {
-      throw new Error("Refresh token expiration not set, make sure to login first.");
-    }
-  }
-
-  /**
-   * Check if the access token is expired or about to expire (within 5 minutes)
-   */
-  private isTokenExpired = (): boolean => {
-    if (!this.auth_info.token_expiration) {
-      return true;
-    }
-    // Refresh if token expires within 5 minutes
-    const bufferTime = 5 * 60 * 1000; // 5 minutes in milliseconds
-    return Date.now() >= this.auth_info.token_expiration.getTime() - bufferTime;
-  }
-
-  /**
-   * Check if the refresh token is expired
-   */
-  private isRefreshTokenExpired = (): boolean => {
-    if (!this.auth_info.refresh_token_expiration) {
-      return true;
-    }
-    return Date.now() >= this.auth_info.refresh_token_expiration.getTime();
-  }
-
-  /**
-   * Refresh the access token using the refresh token
-   */
-  public refreshToken = async (): Promise<boolean> => {
-    if (!this.auth_info.refresh_token) {
-      throw new Error("No refresh token available. Please login again.");
-    }
-
-    if (this.isRefreshTokenExpired()) {
-      throw new Error("Refresh token has expired. Please login again.");
-    }
-
-    const refresh_params = {
-      refresh_token: this.auth_info.refresh_token,
-    };
-
-    // Use fetch directly to avoid triggering ensureValidToken and use PUT method
-    const res = await fetch(this.API_ROOT + "/auth/refresh-token", {
-      method: "PUT",
-      body: JSON.stringify(refresh_params),
-      headers: {
-        "Content-Type": "application/json",
-      },
-    });
-
-    const resJson = (await res.json()) as {
-      error?: string;
-      access_token?: string;
-      refresh_token?: string;
-      expires?: number;
-      expiration_refresh?: number;
-    };
-
-    // Check for error response
-    if (resJson["error"]) {
-      throw new Error(`Failed to refresh token: ${resJson["error"]}`);
-    }
-
-    const access_token = resJson["access_token"] as string;
-    const refresh_token = resJson["refresh_token"] as string | undefined;
-    const expires = resJson["expires"] as number;
-    const expiration_refresh = resJson["expiration_refresh"] as number | undefined;
-
-    if (access_token) {
-      this.auth_info.token = access_token;
-      this.macbid_session_headers["Authorization"] = this.auth_info.token;
-      this.auth_info.token_expiration = new Date(expires * 1000);
-
-      // Update refresh token if a new one is provided
-      if (refresh_token) {
-        this.auth_info.refresh_token = refresh_token;
-      }
-      if (expiration_refresh) {
-        this.auth_info.refresh_token_expiration = new Date(expiration_refresh * 1000);
-      }
-
-      await this.saveTokens();
-      return true;
-    } else {
-      throw new Error("Failed to refresh token: no access token in response");
-    }
-  }
-
-  /**
-   * Ensure the access token is valid, refreshing if necessary
-   */
-  private ensureValidToken = async (): Promise<void> => {
-    if (this.isTokenExpired()) {
-      await this.refreshToken();
-    }
-  }
-
-  /**
-   * Returns the logged in user's favorites, and all of their (visible) attributes.
-   */
-  public get_watchlist = async (): Promise<WatchlistFull[]> => {
-    this.check_auth();
-    const res = await this.get(
-      `/auctions/customer/${this.auth_info["user_id"]}/active-auctions`
-    );
-
-    return (await res.json())["watchlist_full"] as WatchlistFull[];
-  };
-
-  /**
-   * Save tokens to file for persistence across restarts
-   */
-  private saveTokens = async (): Promise<void> => {
-    if (!this.tokenFilePath) {
-      console.log("No token file path provided, skipping token save");
-      return;
-    }
-
-    try {
-      const tokenData = {
-        token: this.auth_info.token,
-        refresh_token: this.auth_info.refresh_token,
-        token_expiration: this.auth_info.token_expiration?.toISOString(),
-        refresh_token_expiration: this.auth_info.refresh_token_expiration?.toISOString(),
-        user_id: this.auth_info.user_id,
-        device_id: this.auth_info.device_id,
-      };
-
-      await fs.writeFile(this.tokenFilePath, JSON.stringify(tokenData, null, 2), "utf-8");
-      console.log("Tokens saved to file:", this.tokenFilePath);
-    } catch (error) {
-      console.warn("Failed to save tokens:", error);
-    }
-  };
-
-  /**
-   * Load tokens from file
-   */
-  public static loadTokens = async (tokenFilePath: string): Promise<Partial<AuthInfo> | null> => {
-    try {
-      const data = await fs.readFile(tokenFilePath, "utf-8");
-      const tokenData = JSON.parse(data) as {
-        token?: string;
-        refresh_token?: string;
-        token_expiration?: string;
-        refresh_token_expiration?: string;
-        user_id?: string;
-        device_id?: string;
-      };
-
-      return {
-        token: tokenData.token,
-        refresh_token: tokenData.refresh_token,
-        token_expiration: tokenData.token_expiration ? new Date(tokenData.token_expiration) : undefined,
-        refresh_token_expiration: tokenData.refresh_token_expiration ? new Date(tokenData.refresh_token_expiration) : undefined,
-        user_id: tokenData.user_id,
-        device_id: tokenData.device_id,
-      };
-    } catch (error) {
-      // File doesn't exist or is invalid, return null
-      return null;
-    }
-  };
-}
-
-export default MacBid;

package/index.ts

@@ -1,2 +0,0 @@
-export { default } from "./MacBid.js";
-export * from "./MacBid.js";