@bubblebridge/sdk 0.0.0-stage → 0.1.1

package/dist/generated.js

@@ -0,0 +1,5 @@
+/**
+ * This file was auto-generated by openapi-typescript.
+ * Do not make direct changes to the file.
+ */
+export {};

package/dist/gmail.d.ts

@@ -0,0 +1,16 @@
+import type { Google } from './google.js';
+/** One plain text email from the user's account. */
+export interface SendEmail {
+    to: string;
+    subject: string;
+    text: string;
+}
+/** The Gmail helpers. `Google.gmail` holds it. */
+export declare class Gmail {
+    private readonly google;
+    constructor(google: Google);
+    /** Sends the email. It returns the Gmail message resource. */
+    send(email: SendEmail): Promise<unknown>;
+    /** Lists the message IDs that match a Gmail search query. */
+    listMessages(query: string, maxResults: number): Promise<unknown>;
+}

package/dist/gmail.js

@@ -0,0 +1,26 @@
+/** The Gmail helpers. `Google.gmail` holds it. */
+export class Gmail {
+    google;
+    constructor(google) {
+        this.google = google;
+    }
+    /** Sends the email. It returns the Gmail message resource. */
+    send(email) {
+        const message = `To: ${email.to}\r\nSubject: ${email.subject}\r\nContent-Type: text/plain; charset=utf-8\r\n\r\n${email.text}`;
+        return this.google.request('POST', '/gmail/v1/users/me/messages/send', {
+            raw: base64Url(message),
+        });
+    }
+    /** Lists the message IDs that match a Gmail search query. */
+    listMessages(query, maxResults) {
+        const params = new URLSearchParams({ q: query, maxResults: String(maxResults) });
+        return this.google.request('GET', `/gmail/v1/users/me/messages?${params}`);
+    }
+}
+function base64Url(text) {
+    const bytes = new TextEncoder().encode(text);
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}

package/dist/google.d.ts

@@ -0,0 +1,13 @@
+import { Calendar } from './calendar.js';
+import { Gmail } from './gmail.js';
+import type { Method } from './types.js';
+import type { UserClient } from './user.js';
+/** The Google provider of one user. `UserClient.google` holds it. */
+export declare class Google {
+    private readonly user;
+    readonly gmail: Gmail;
+    readonly calendar: Calendar;
+    constructor(user: UserClient);
+    /** Sends one call to any Google path on the allowlist through the proxy. */
+    request<T = unknown>(method: Method, path: string, body?: unknown): Promise<T>;
+}

package/dist/google.js

@@ -0,0 +1,15 @@
+import { Calendar } from './calendar.js';
+import { Gmail } from './gmail.js';
+/** The Google provider of one user. `UserClient.google` holds it. */
+export class Google {
+    user;
+    gmail = new Gmail(this);
+    calendar = new Calendar(this);
+    constructor(user) {
+        this.user = user;
+    }
+    /** Sends one call to any Google path on the allowlist through the proxy. */
+    request(method, path, body) {
+        return this.user.send(method, `/v1/providers/google${path}`, body);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+import { Oauth } from './oauth.js';
+import { UserClient, type ForUserOptions } from './user.js';
+import type { TokenResponse } from './types.js';
+export type { components, operations, paths } from './generated.js';
+export type { Connection, ConnectionList, ConnectionStatus, Method, Scope, TokenResponse, } from './types.js';
+export { ApiError, UpstreamError } from './error.js';
+export { Oauth, type AuthorizeUrlInput, type ExchangeCodeInput } from './oauth.js';
+export { UserClient, type ForUserOptions, type OnTokensUpdated } from './user.js';
+export { Google } from './google.js';
+export { Gmail, type SendEmail } from './gmail.js';
+export { Calendar, type NewEvent } from './calendar.js';
+export interface BubbleBridgeOptions {
+    clientId: string;
+    clientSecret: string;
+}
+/** One client for one agent. It holds the client ID and the client secret of the agent. */
+export declare class BubbleBridge {
+    readonly clientId: string;
+    readonly clientSecret: string;
+    readonly baseUrl = "https://bubblebridge.io";
+    readonly apiUrl = "https://api.bubblebridge.io";
+    readonly oauth: Oauth;
+    constructor({ clientId, clientSecret }: BubbleBridgeOptions);
+    /** A client for one user. `onTokensUpdated` runs after each token rotation. */
+    forUser(tokens: TokenResponse, options?: ForUserOptions): UserClient;
+}

package/dist/index.js

@@ -0,0 +1,24 @@
+import { Oauth } from './oauth.js';
+import { UserClient } from './user.js';
+export { ApiError, UpstreamError } from './error.js';
+export { Oauth } from './oauth.js';
+export { UserClient } from './user.js';
+export { Google } from './google.js';
+export { Gmail } from './gmail.js';
+export { Calendar } from './calendar.js';
+/** One client for one agent. It holds the client ID and the client secret of the agent. */
+export class BubbleBridge {
+    clientId;
+    clientSecret;
+    baseUrl = 'https://bubblebridge.io';
+    apiUrl = 'https://api.bubblebridge.io';
+    oauth = new Oauth(this);
+    constructor({ clientId, clientSecret }) {
+        this.clientId = clientId;
+        this.clientSecret = clientSecret;
+    }
+    /** A client for one user. `onTokensUpdated` runs after each token rotation. */
+    forUser(tokens, options = {}) {
+        return new UserClient(this, tokens, options.onTokensUpdated);
+    }
+}

package/dist/oauth.d.ts

@@ -0,0 +1,25 @@
+import type { BubbleBridge } from './index.js';
+import type { Scope, TokenResponse } from './types.js';
+export interface AuthorizeUrlInput {
+    scopes: Scope[];
+    redirectUri: string;
+    state: string;
+    codeChallenge: string;
+}
+export interface ExchangeCodeInput {
+    code: string;
+    codeVerifier: string;
+    redirectUri: string;
+}
+/** The OAuth functions of a client. `BubbleBridge.oauth` holds it. */
+export declare class Oauth {
+    private readonly client;
+    constructor(client: BubbleBridge);
+    /** The URL of the consent page. The agent site sends the browser to it. */
+    authorizeUrl({ scopes, redirectUri, state, codeChallenge }: AuthorizeUrlInput): string;
+    /** Exchanges the authorization code for the first token pair. */
+    exchangeCode({ code, codeVerifier, redirectUri }: ExchangeCodeInput): Promise<TokenResponse>;
+    /** Exchanges a refresh token for a new token pair. The API rotates the refresh token. */
+    refresh(refreshToken: string): Promise<TokenResponse>;
+    private token;
+}

package/dist/oauth.js

@@ -0,0 +1,50 @@
+import { ApiError } from './error.js';
+/** The OAuth functions of a client. `BubbleBridge.oauth` holds it. */
+export class Oauth {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /** The URL of the consent page. The agent site sends the browser to it. */
+    authorizeUrl({ scopes, redirectUri, state, codeChallenge }) {
+        const query = new URLSearchParams({
+            client_id: this.client.clientId,
+            redirect_uri: redirectUri,
+            scope: scopes.join(' '),
+            state,
+            code_challenge: codeChallenge,
+        });
+        return `${this.client.baseUrl}/authorize?${query}`;
+    }
+    /** Exchanges the authorization code for the first token pair. */
+    exchangeCode({ code, codeVerifier, redirectUri }) {
+        return this.token({
+            grant_type: 'authorization_code',
+            code,
+            code_verifier: codeVerifier,
+            redirect_uri: redirectUri,
+            client_id: this.client.clientId,
+            client_secret: this.client.clientSecret,
+        });
+    }
+    /** Exchanges a refresh token for a new token pair. The API rotates the refresh token. */
+    refresh(refreshToken) {
+        return this.token({
+            grant_type: 'refresh_token',
+            refresh_token: refreshToken,
+            client_id: this.client.clientId,
+            client_secret: this.client.clientSecret,
+        });
+    }
+    async token(request) {
+        const response = await fetch(`${this.client.apiUrl}/oauth/token`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(request),
+        });
+        if (response.ok)
+            return (await response.json());
+        const { error } = (await response.json());
+        throw new ApiError(response.status, error);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,10 @@
+import type { components } from './generated.js';
+export type Scope = components['schemas']['Scope'];
+export type TokenRequest = components['schemas']['TokenRequest'];
+export type TokenResponse = components['schemas']['TokenResponse'];
+export type ErrorBody = components['schemas']['ErrorBody'];
+export type ErrorResponse = components['schemas']['ErrorResponse'];
+export type Connection = components['schemas']['Connection'];
+export type ConnectionList = components['schemas']['ConnectionList'];
+export type ConnectionStatus = components['schemas']['ConnectionStatus'];
+export type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/user.d.ts

@@ -0,0 +1,25 @@
+import { Google } from './google.js';
+import type { BubbleBridge } from './index.js';
+import type { ConnectionList, Method, TokenResponse } from './types.js';
+/** The builder stores the new token pair in this callback. It runs after each rotation. */
+export type OnTokensUpdated = (tokens: TokenResponse) => void;
+export interface ForUserOptions {
+    onTokensUpdated?: OnTokensUpdated;
+}
+/** One client for one user. `BubbleBridge.forUser` returns it. */
+export declare class UserClient {
+    readonly client: BubbleBridge;
+    private readonly onTokensUpdated?;
+    readonly google: Google;
+    private tokens;
+    private expiresAt;
+    private refreshing?;
+    constructor(client: BubbleBridge, tokens: TokenResponse, onTokensUpdated?: OnTokensUpdated | undefined);
+    /** A valid access token. It refreshes the token pair first if the access token has expired. */
+    accessToken(): Promise<string>;
+    /** The connections that the user enabled for the agent. */
+    connections(): Promise<ConnectionList>;
+    /** Sends one call to the API with the agent access token. */
+    send<T>(method: Method, pathAndQuery: string, body?: unknown): Promise<T>;
+    private refresh;
+}

package/dist/user.js

@@ -0,0 +1,59 @@
+import { errorFromResponse } from './error.js';
+import { Google } from './google.js';
+/** The proxy may receive the token a few seconds after the SDK reads the expiry. */
+const REFRESH_MARGIN_MS = 60_000;
+/** One client for one user. `BubbleBridge.forUser` returns it. */
+export class UserClient {
+    client;
+    onTokensUpdated;
+    google = new Google(this);
+    tokens;
+    expiresAt;
+    refreshing;
+    constructor(client, tokens, onTokensUpdated) {
+        this.client = client;
+        this.onTokensUpdated = onTokensUpdated;
+        this.tokens = tokens;
+        this.expiresAt = expiresAt(tokens);
+    }
+    /** A valid access token. It refreshes the token pair first if the access token has expired. */
+    accessToken() {
+        if (this.expiresAt > Date.now() + REFRESH_MARGIN_MS) {
+            return Promise.resolve(this.tokens.access_token);
+        }
+        this.refreshing ??= this.refresh().finally(() => {
+            this.refreshing = undefined;
+        });
+        return this.refreshing;
+    }
+    /** The connections that the user enabled for the agent. */
+    connections() {
+        return this.send('GET', '/v1/connections');
+    }
+    /** Sends one call to the API with the agent access token. */
+    async send(method, pathAndQuery, body) {
+        const headers = {
+            authorization: `Bearer ${await this.accessToken()}`,
+        };
+        if (body !== undefined)
+            headers['content-type'] = 'application/json';
+        const response = await fetch(`${this.client.apiUrl}${pathAndQuery}`, {
+            method,
+            headers,
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        if (response.ok)
+            return (await response.json());
+        throw errorFromResponse(response.status, await response.text());
+    }
+    async refresh() {
+        const response = await this.client.oauth.refresh(this.tokens.refresh_token);
+        this.tokens = response;
+        this.expiresAt = expiresAt(response);
+        this.onTokensUpdated?.(response);
+        return response.access_token;
+    }
+}
+function expiresAt(tokens) {
+    return Date.now() + tokens.expires_in * 1000;
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@bubblebridge/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "The BubbleBridge SDK for agent builders",
+  "keywords": ["bubblebridge", "oauth", "gmail", "google-calendar", "agent"],
+  "homepage": "https://bubblebridge.io",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bekzodaka/bubble-bridge.git",
+    "directory": "sdk-ts"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src",
+    "generate": "openapi-typescript ../openapi.json -o src/generated.ts",
+    "prepublishOnly": "npm run lint && npm run build"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9",
+    "eslint": "^9",
+    "openapi-typescript": "^7",
+    "typescript": "^5",
+    "typescript-eslint": "^8"
+  }
+}