inbox.dog 0.1.0

package/README.md

@@ -0,0 +1,114 @@
+# inbox.dog
+
+Gmail OAuth tokens in 3 API calls. No Google Cloud console required.
+
+```
+npm install inbox.dog
+```
+
+## Quick start
+
+```ts
+import { InboxDog } from "inbox.dog";
+
+const dog = new InboxDog();
+
+// 1. Create an API key (one-time)
+const key = await dog.createKey("my-app");
+// → { client_id, client_secret, name, credits: 10 }
+
+// 2. Redirect user to Gmail consent
+const url = dog.getAuthUrl({
+  clientId: key.client_id,
+  redirectUri: "http://localhost:3000/callback",
+  scope: "email",
+});
+// → redirect user to `url`
+
+// 3. Exchange the code from callback for tokens
+const tokens = await dog.exchangeCode(code, key.client_id, key.client_secret);
+// → { access_token, refresh_token, email, expires_in }
+
+// Use tokens directly with Gmail API
+const res = await fetch("https://gmail.googleapis.com/gmail/v1/users/me/messages", {
+  headers: { Authorization: `Bearer ${tokens.access_token}` },
+});
+```
+
+## API
+
+### `new InboxDog(options?)`
+
+| Option    | Type       | Default               |
+|-----------|------------|-----------------------|
+| `baseUrl` | `string`   | `https://inbox.dog`   |
+| `fetch`   | `Function` | `globalThis.fetch`    |
+
+### `createKey(name?): Promise<CreateKeyResponse>`
+
+Create a new API key. Returns `{ client_id, client_secret, name, credits }`.
+
+### `getKey(clientId, clientSecret): Promise<KeyInfo>`
+
+Get key info. Returns `{ client_id, name, credits, created_at }`.
+
+### `getAuthUrl(opts): string`
+
+Build the OAuth authorization URL. No network request.
+
+| Param         | Type     | Required |
+|---------------|----------|----------|
+| `clientId`    | `string` | yes      |
+| `redirectUri` | `string` | yes      |
+| `scope`       | `Scope`  | no       |
+| `state`       | `string` | no       |
+
+Scopes: `"email"` (default, read-only), `"email:read"`, `"email:send"`, `"email:full"`.
+
+### `exchangeCode(code, clientId, clientSecret): Promise<TokenResponse>`
+
+Exchange auth code for tokens. Costs 1 credit.
+
+Returns `{ access_token, refresh_token, token_type, expires_in, email }`.
+
+### `refreshToken(refreshToken, clientId, clientSecret): Promise<RefreshResponse>`
+
+Refresh an expired access token. Free.
+
+Returns `{ access_token, token_type, expires_in }`.
+
+### `checkout(clientId, clientSecret, credits?): Promise<CheckoutResponse>`
+
+Create a Stripe checkout session. Returns `{ checkout_url, session_id }`.
+
+## Errors
+
+All errors throw `InboxDogError` with these properties:
+
+| Property  | Type     | Description            |
+|-----------|----------|------------------------|
+| `code`    | `string` | Machine-readable code  |
+| `status`  | `number` | HTTP status code       |
+| `message` | `string` | Human-readable message |
+| `action`  | `string` | Suggested fix          |
+| `docs`    | `string` | Link to docs           |
+
+Error codes: `INVALID_CREDENTIALS` (401), `INSUFFICIENT_CREDITS` (402), `VALIDATION_ERROR` (400), `STATE_NOT_FOUND` (400), `AUTH_CODE_NOT_FOUND` (400), `TOKEN_EXCHANGE_FAILED` (500).
+
+```ts
+try {
+  await dog.exchangeCode(code, clientId, clientSecret);
+} catch (e) {
+  if (e instanceof InboxDogError && e.code === "INSUFFICIENT_CREDITS") {
+    const { checkout_url } = await dog.checkout(clientId, clientSecret);
+    // redirect user to checkout_url
+  }
+}
+```
+
+## Links
+
+- Docs: https://inbox.dog/docs
+- API Reference: https://inbox.dog/docs/api
+- GitHub: https://github.com/acoyfellow/inbox.dog
+- MCP Server: `npx @inboxdog/mcp-server`

package/dist/index.cjs

@@ -0,0 +1,130 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  InboxDog: () => InboxDog,
+  InboxDogError: () => InboxDogError,
+  createClient: () => createClient,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_BASE_URL = "https://inbox.dog";
+var InboxDogError = class extends Error {
+  constructor(status, detail) {
+    super(detail.message);
+    this.name = "InboxDogError";
+    this.code = detail.code;
+    this.status = status;
+    this.action = detail.action;
+    this.docs = detail.docs;
+  }
+};
+var InboxDog = class {
+  constructor(opts = {}) {
+    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.fetchFn = opts.fetch ?? globalThis.fetch;
+  }
+  // ── API Keys ───────────────────────────────────────
+  /** Create a new API key. Returns client_id, client_secret, and 10 free credits. */
+  async createKey(name) {
+    return this.post("/api/keys", { name: name ?? "default" });
+  }
+  /** Get API key info (credits remaining, creation date). */
+  async getKey(clientId, clientSecret) {
+    return this.request(`/api/keys/${clientId}`, {
+      headers: { "X-Client-Secret": clientSecret }
+    });
+  }
+  // ── OAuth ──────────────────────────────────────────
+  /**
+   * Build the authorization URL to redirect users to.
+   * This is a pure URL builder — no network request.
+   */
+  getAuthUrl(opts) {
+    const url = new URL(`${this.baseUrl}/oauth/authorize`);
+    url.searchParams.set("client_id", opts.clientId);
+    url.searchParams.set("redirect_uri", opts.redirectUri);
+    if (opts.scope) url.searchParams.set("scope", opts.scope);
+    if (opts.state) url.searchParams.set("state", opts.state);
+    return url.toString();
+  }
+  /** Exchange an authorization code for access + refresh tokens. Costs 1 credit. */
+  async exchangeCode(code, clientId, clientSecret) {
+    return this.post("/oauth/token", {
+      code,
+      client_id: clientId,
+      client_secret: clientSecret
+    });
+  }
+  /** Refresh an expired access token. Free, no credit cost. */
+  async refreshToken(refreshToken, clientId, clientSecret) {
+    return this.post("/oauth/token", {
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+      client_id: clientId,
+      client_secret: clientSecret
+    });
+  }
+  // ── Billing ────────────────────────────────────────
+  /** Create a Stripe checkout session to purchase credits. */
+  async checkout(clientId, clientSecret, credits) {
+    return this.post("/api/checkout", {
+      client_id: clientId,
+      client_secret: clientSecret,
+      credits: credits ?? 100
+    });
+  }
+  // ── Internal ───────────────────────────────────────
+  async request(path, init = {}) {
+    const res = await this.fetchFn(`${this.baseUrl}${path}`, {
+      ...init,
+      headers: {
+        "Content-Type": "application/json",
+        ...init.headers
+      }
+    });
+    const body = await res.json();
+    if (!res.ok) {
+      const err = body;
+      throw new InboxDogError(res.status, err.error ?? {
+        code: "UNKNOWN",
+        message: `HTTP ${res.status}`
+      });
+    }
+    return body;
+  }
+  async post(path, data) {
+    return this.request(path, {
+      method: "POST",
+      body: JSON.stringify(data)
+    });
+  }
+};
+function createClient(opts) {
+  return new InboxDog(opts);
+}
+var index_default = InboxDog;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  InboxDog,
+  InboxDogError,
+  createClient
+});

package/dist/index.d.cts

@@ -0,0 +1,80 @@
+/** inbox.dog — Gmail OAuth tokens in 3 API calls */
+type Scope = "email" | "email:read" | "email:send" | "email:full";
+interface CreateKeyResponse {
+    client_id: string;
+    client_secret: string;
+    name: string;
+    credits: number;
+}
+interface KeyInfo {
+    client_id: string;
+    name: string;
+    credits: number;
+    created_at: number;
+}
+interface TokenResponse {
+    access_token: string;
+    refresh_token: string;
+    token_type: "Bearer";
+    expires_in: number;
+    email: string;
+}
+interface RefreshResponse {
+    access_token: string;
+    token_type: "Bearer";
+    expires_in: number;
+}
+interface CheckoutResponse {
+    checkout_url: string;
+    session_id: string;
+}
+interface InboxDogErrorDetail {
+    code: string;
+    message: string;
+    action?: string;
+    docs?: string;
+}
+declare class InboxDogError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly action?: string;
+    readonly docs?: string;
+    constructor(status: number, detail: InboxDogErrorDetail);
+}
+interface InboxDogOptions {
+    /** Override the base URL (default: https://inbox.dog) */
+    baseUrl?: string;
+    /** Provide a custom fetch implementation */
+    fetch?: typeof globalThis.fetch;
+}
+declare class InboxDog {
+    private baseUrl;
+    private fetchFn;
+    constructor(opts?: InboxDogOptions);
+    /** Create a new API key. Returns client_id, client_secret, and 10 free credits. */
+    createKey(name?: string): Promise<CreateKeyResponse>;
+    /** Get API key info (credits remaining, creation date). */
+    getKey(clientId: string, clientSecret: string): Promise<KeyInfo>;
+    /**
+     * Build the authorization URL to redirect users to.
+     * This is a pure URL builder — no network request.
+     */
+    getAuthUrl(opts: {
+        clientId: string;
+        redirectUri: string;
+        scope?: Scope;
+        state?: string;
+    }): string;
+    /** Exchange an authorization code for access + refresh tokens. Costs 1 credit. */
+    exchangeCode(code: string, clientId: string, clientSecret: string): Promise<TokenResponse>;
+    /** Refresh an expired access token. Free, no credit cost. */
+    refreshToken(refreshToken: string, clientId: string, clientSecret: string): Promise<RefreshResponse>;
+    /** Create a Stripe checkout session to purchase credits. */
+    checkout(clientId: string, clientSecret: string, credits?: number): Promise<CheckoutResponse>;
+    private request;
+    private post;
+}
+/** Create an InboxDog client with default options. */
+declare function createClient(opts?: InboxDogOptions): InboxDog;
+
+export { type CheckoutResponse, type CreateKeyResponse, InboxDog, InboxDogError, type InboxDogErrorDetail, type InboxDogOptions, type KeyInfo, type RefreshResponse, type Scope, type TokenResponse, createClient, InboxDog as default };

package/dist/index.d.ts

@@ -0,0 +1,80 @@
+/** inbox.dog — Gmail OAuth tokens in 3 API calls */
+type Scope = "email" | "email:read" | "email:send" | "email:full";
+interface CreateKeyResponse {
+    client_id: string;
+    client_secret: string;
+    name: string;
+    credits: number;
+}
+interface KeyInfo {
+    client_id: string;
+    name: string;
+    credits: number;
+    created_at: number;
+}
+interface TokenResponse {
+    access_token: string;
+    refresh_token: string;
+    token_type: "Bearer";
+    expires_in: number;
+    email: string;
+}
+interface RefreshResponse {
+    access_token: string;
+    token_type: "Bearer";
+    expires_in: number;
+}
+interface CheckoutResponse {
+    checkout_url: string;
+    session_id: string;
+}
+interface InboxDogErrorDetail {
+    code: string;
+    message: string;
+    action?: string;
+    docs?: string;
+}
+declare class InboxDogError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly action?: string;
+    readonly docs?: string;
+    constructor(status: number, detail: InboxDogErrorDetail);
+}
+interface InboxDogOptions {
+    /** Override the base URL (default: https://inbox.dog) */
+    baseUrl?: string;
+    /** Provide a custom fetch implementation */
+    fetch?: typeof globalThis.fetch;
+}
+declare class InboxDog {
+    private baseUrl;
+    private fetchFn;
+    constructor(opts?: InboxDogOptions);
+    /** Create a new API key. Returns client_id, client_secret, and 10 free credits. */
+    createKey(name?: string): Promise<CreateKeyResponse>;
+    /** Get API key info (credits remaining, creation date). */
+    getKey(clientId: string, clientSecret: string): Promise<KeyInfo>;
+    /**
+     * Build the authorization URL to redirect users to.
+     * This is a pure URL builder — no network request.
+     */
+    getAuthUrl(opts: {
+        clientId: string;
+        redirectUri: string;
+        scope?: Scope;
+        state?: string;
+    }): string;
+    /** Exchange an authorization code for access + refresh tokens. Costs 1 credit. */
+    exchangeCode(code: string, clientId: string, clientSecret: string): Promise<TokenResponse>;
+    /** Refresh an expired access token. Free, no credit cost. */
+    refreshToken(refreshToken: string, clientId: string, clientSecret: string): Promise<RefreshResponse>;
+    /** Create a Stripe checkout session to purchase credits. */
+    checkout(clientId: string, clientSecret: string, credits?: number): Promise<CheckoutResponse>;
+    private request;
+    private post;
+}
+/** Create an InboxDog client with default options. */
+declare function createClient(opts?: InboxDogOptions): InboxDog;
+
+export { type CheckoutResponse, type CreateKeyResponse, InboxDog, InboxDogError, type InboxDogErrorDetail, type InboxDogOptions, type KeyInfo, type RefreshResponse, type Scope, type TokenResponse, createClient, InboxDog as default };

package/dist/index.js

@@ -0,0 +1,103 @@
+// src/index.ts
+var DEFAULT_BASE_URL = "https://inbox.dog";
+var InboxDogError = class extends Error {
+  constructor(status, detail) {
+    super(detail.message);
+    this.name = "InboxDogError";
+    this.code = detail.code;
+    this.status = status;
+    this.action = detail.action;
+    this.docs = detail.docs;
+  }
+};
+var InboxDog = class {
+  constructor(opts = {}) {
+    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.fetchFn = opts.fetch ?? globalThis.fetch;
+  }
+  // ── API Keys ───────────────────────────────────────
+  /** Create a new API key. Returns client_id, client_secret, and 10 free credits. */
+  async createKey(name) {
+    return this.post("/api/keys", { name: name ?? "default" });
+  }
+  /** Get API key info (credits remaining, creation date). */
+  async getKey(clientId, clientSecret) {
+    return this.request(`/api/keys/${clientId}`, {
+      headers: { "X-Client-Secret": clientSecret }
+    });
+  }
+  // ── OAuth ──────────────────────────────────────────
+  /**
+   * Build the authorization URL to redirect users to.
+   * This is a pure URL builder — no network request.
+   */
+  getAuthUrl(opts) {
+    const url = new URL(`${this.baseUrl}/oauth/authorize`);
+    url.searchParams.set("client_id", opts.clientId);
+    url.searchParams.set("redirect_uri", opts.redirectUri);
+    if (opts.scope) url.searchParams.set("scope", opts.scope);
+    if (opts.state) url.searchParams.set("state", opts.state);
+    return url.toString();
+  }
+  /** Exchange an authorization code for access + refresh tokens. Costs 1 credit. */
+  async exchangeCode(code, clientId, clientSecret) {
+    return this.post("/oauth/token", {
+      code,
+      client_id: clientId,
+      client_secret: clientSecret
+    });
+  }
+  /** Refresh an expired access token. Free, no credit cost. */
+  async refreshToken(refreshToken, clientId, clientSecret) {
+    return this.post("/oauth/token", {
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+      client_id: clientId,
+      client_secret: clientSecret
+    });
+  }
+  // ── Billing ────────────────────────────────────────
+  /** Create a Stripe checkout session to purchase credits. */
+  async checkout(clientId, clientSecret, credits) {
+    return this.post("/api/checkout", {
+      client_id: clientId,
+      client_secret: clientSecret,
+      credits: credits ?? 100
+    });
+  }
+  // ── Internal ───────────────────────────────────────
+  async request(path, init = {}) {
+    const res = await this.fetchFn(`${this.baseUrl}${path}`, {
+      ...init,
+      headers: {
+        "Content-Type": "application/json",
+        ...init.headers
+      }
+    });
+    const body = await res.json();
+    if (!res.ok) {
+      const err = body;
+      throw new InboxDogError(res.status, err.error ?? {
+        code: "UNKNOWN",
+        message: `HTTP ${res.status}`
+      });
+    }
+    return body;
+  }
+  async post(path, data) {
+    return this.request(path, {
+      method: "POST",
+      body: JSON.stringify(data)
+    });
+  }
+};
+function createClient(opts) {
+  return new InboxDog(opts);
+}
+var index_default = InboxDog;
+export {
+  InboxDog,
+  InboxDogError,
+  createClient,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "inbox.dog",
+  "version": "0.1.0",
+  "description": "Gmail OAuth tokens in 3 API calls. No Google Cloud console required.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "echo 'No tests yet'",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "gmail",
+    "oauth",
+    "email",
+    "google",
+    "oauth2",
+    "api",
+    "tokens"
+  ],
+  "author": "acoyfellow",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/acoyfellow/inbox.dog",
+    "directory": "package"
+  },
+  "homepage": "https://inbox.dog",
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0"
+  }
+}