@bubblebridge/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BubbleBridge
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# @bubblebridge/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The BubbleBridge SDK for agent builders. BubbleBridge is a proxy between users and AI agents. Your agent calls Gmail and Google Calendar through BubbleBridge. Your agent never receives the Google credentials of the user.
+
+The package is TypeScript. It has no runtime dependency. It runs on Node.js 20 and later and in the browser.
+
+## Install
+
+```sh
+npm install @bubblebridge/sdk
+```
+
+## Register your agent
+
+You need a client ID and a client secret. Register your agent at `https://bubblebridge.io/build`. Keep the client secret in a secret store.
+
+## Send a user to the consent page
+
+Create a `state` value and a PKCE verifier. Store both for at most ten minutes. Then send the browser to the consent page.
+
+```ts
+import { createHash, randomBytes } from 'node:crypto';
+import { BubbleBridge } from '@bubblebridge/sdk';
+
+const bb = new BubbleBridge({ clientId, clientSecret });
+
+const state = randomBytes(16).toString('base64url');
+const codeVerifier = randomBytes(32).toString('base64url');
+const codeChallenge = createHash('sha256').update(codeVerifier).digest('base64url');
+
+const location = bb.oauth.authorizeUrl({
+  scopes: ['google.gmail.readonly', 'google.calendar.events'],
+  redirectUri,
+  state,
+  codeChallenge,
+});
+```
+
+The user clicks Allow. The browser opens `<redirectUri>?code=...&state=...`.
+
+## Exchange the code
+
+Compare `state` with the stored value. Then exchange the code for the first token pair. Store the whole object under `user_id`.
+
+```ts
+const tokens = await bb.oauth.exchangeCode({ code, codeVerifier, redirectUri });
+await putUser(tokens.user_id, tokens);
+```
+
+## Call Google for a user
+
+Load the stored token pair. Set `expires_in` to `0`. This forces a refresh on the first call. BubbleBridge rotates the refresh token on each refresh. `onTokensUpdated` runs after each rotation. Store the new pair every time.
+
+```ts
+const user = bb.forUser(
+  { ...tokens, expires_in: 0 },
+  { onTokensUpdated: (fresh) => void putUser(userId, fresh) },
+);
+
+await user.google.gmail.send({ to, subject, text });
+const messages = await user.google.gmail.listMessages('newer_than:1d', 20);
+const events = await user.google.calendar.listEvents('primary', timeMin);
+await user.google.calendar.createEvent('primary', { summary, start, end });
+```
+
+Use one `UserClient` for all parallel calls of one user. The client runs one refresh at a time.
+
+Use `request` for a Google path that has no helper function. Give the method, the provider path with its query string, and an optional JSON body.
+
+```ts
+const message = await user.google.request('GET', `/gmail/v1/users/me/messages/${id}?format=metadata`);
+```
+
+The proxy returns the Google response as is. The SDK returns it as `unknown`.
+
+## Scopes
+
+| Scope | Access |
+|---|---|
+| `google.gmail.readonly` | Read messages. |
+| `google.gmail.send` | Send messages. |
+| `google.calendar.readonly` | Read events. |
+| `google.calendar.events` | Read and create events. |
+
+## Errors
+
+An API error throws `ApiError` with `status` and `body`. The `body` has `code`, `message`, and `request_id`. A Google error passes through the proxy and throws `UpstreamError` with the Google status and the body text. A network failure throws the `fetch` error.
+
+## Guide
+
+The full builder guide is at `https://bubblebridge.io/builder-guide.txt`.
+
+## License
+
+MIT

package/dist/calendar.d.ts

@@ -0,0 +1,17 @@
+import type { Google } from './google.js';
+/** One event with RFC 3339 start and end times. */
+export interface NewEvent {
+    summary: string;
+    description?: string;
+    start: string;
+    end: string;
+}
+/** The Calendar helpers. `Google.calendar` holds it. */
+export declare class Calendar {
+    private readonly google;
+    constructor(google: Google);
+    /** Lists the single events of a calendar that start at or after `timeMin`, in start order. */
+    listEvents(calendarId: string, timeMin: string): Promise<unknown>;
+    /** Creates the event. It returns the Calendar event resource. */
+    createEvent(calendarId: string, event: NewEvent): Promise<unknown>;
+}

package/dist/calendar.js

@@ -0,0 +1,25 @@
+/** The Calendar helpers. `Google.calendar` holds it. */
+export class Calendar {
+    google;
+    constructor(google) {
+        this.google = google;
+    }
+    /** Lists the single events of a calendar that start at or after `timeMin`, in start order. */
+    listEvents(calendarId, timeMin) {
+        const params = new URLSearchParams({
+            timeMin,
+            singleEvents: 'true',
+            orderBy: 'startTime',
+        });
+        return this.google.request('GET', `/calendar/v3/calendars/${calendarId}/events?${params}`);
+    }
+    /** Creates the event. It returns the Calendar event resource. */
+    createEvent(calendarId, event) {
+        return this.google.request('POST', `/calendar/v3/calendars/${calendarId}/events`, {
+            summary: event.summary,
+            description: event.description,
+            start: { dateTime: event.start },
+            end: { dateTime: event.end },
+        });
+    }
+}

package/dist/error.d.ts

@@ -0,0 +1,14 @@
+import type { ErrorBody } from './types.js';
+/** An error body that the API returned. */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly body: ErrorBody;
+    constructor(status: number, body: ErrorBody);
+}
+/** A status and body that a provider returned through the proxy. */
+export declare class UpstreamError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(status: number, body: string);
+}
+export declare function errorFromResponse(status: number, text: string): ApiError | UpstreamError;

package/dist/error.js

@@ -0,0 +1,36 @@
+/** An error body that the API returned. */
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`api error ${status} ${body.code}: ${body.message}`);
+        this.status = status;
+        this.body = body;
+        this.name = 'ApiError';
+    }
+}
+/** A status and body that a provider returned through the proxy. */
+export class UpstreamError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`upstream error ${status}: ${body}`);
+        this.status = status;
+        this.body = body;
+        this.name = 'UpstreamError';
+    }
+}
+export function errorFromResponse(status, text) {
+    const parsed = tryParseJson(text);
+    if (parsed?.error)
+        return new ApiError(status, parsed.error);
+    return new UpstreamError(status, text);
+}
+function tryParseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}