Build an Extension

# 1. Create the extension catalog entry
curl -X POST https://api.usethrottle.dev/api/v1/extensions \
  -H "Authorization: Bearer <dashboard-session>" \
  -H "content-type: application/json" \
  -d '{
    "name": "Inventory Sidebar",
    "iframeUrl": "https://extensions.example.com/inventory",
    "webhookUrl": "https://extensions.example.com/webhooks",
    "eventSubscriptions": ["order.created", "order.completed"],
    "scopes": ["orders:read", "customers:read"]
  }'
# → { data: { id: "ext_...", name: "Inventory Sidebar", lifecycle: "draft", ... } }

# 2. Create a version (snapshots the current manifest)
curl -X POST https://api.usethrottle.dev/api/v1/extensions/ext_xxx/versions \
  -H "Authorization: Bearer <dashboard-session>" \
  -H "content-type: application/json" \
  -d '{ "version": "1.0.0", "notes": "Initial release" }'
# → { data: { id: "ver_...", version: "1.0.0", status: "draft", ... } }

# 3. Publish the version (marks it installable)
curl -X POST https://api.usethrottle.dev/api/v1/extensions/ext_xxx/versions/ver_xxx/publish \
  -H "Authorization: Bearer <dashboard-session>" \
  -H "content-type: application/json" \
  -d '{}'
# → { data: { id: "ver_...", status: "published", ... } }

# 4. Install into an application (requires X-Throttle-Application-Id header)
curl -X POST https://api.usethrottle.dev/api/v1/extensions/ext_xxx/install \
  -H "Authorization: Bearer <dashboard-session>" \
  -H "X-Throttle-Application-Id: <applicationId>" \
  -H "X-Throttle-Environment-Id: <workspace-environment-uuid>" \
  -H "content-type: application/json" \
  -d '{ "versionId": "ver_xxx" }'

# Response (show once — store both values immediately):
# {
#   "data": {
#     "id": "inst_...",
#     "extensionId": "ext_xxx",
#     "versionId": "ver_xxx",
#     "status": "active",
#     "environmentId": "8a5f2d1e-3d2a-4d24-93a1-fd3f9e1f37f0",
#     "environmentSlug": "uat",
#     "environmentKind": "non_production",
#     "providerEnvironment": "sandbox",
#     "apiKey": "sk_uat_...",             ← store this securely; shown once
#     "webhookSigningSecret": "whsec_..."  ← only present if webhookUrl was declared; shown once
#   }
# }

<!-- Option A: hosted script (no build step) -->
<script src="https://docs.usethrottle.dev/extension-bridge.v1.js"></script>
<script>
  const bridge = window.ThrottleBridge.createBridge({
    // Lock to the dashboard origin in production to prevent token leaks.
    targetOrigin: 'https://app.usethrottle.dev',
  });

  bridge.ready.then((ctx) => {
    console.log('Extension running as', ctx.user.email, 'in', ctx.environment.environmentSlug);

    // Call any Throttle API route the extension's scopes allow.
    bridge.api.get('/api/v1/orders?limit=10').then((res) => {
      console.log('Recent orders:', res.data);
    });

    // Resize the dashboard iframe panel to fit your content.
    bridge.resize(480);

    // Show a toast notification in the dashboard.
    bridge.toast('Inventory synced', 'success');

    // Ask the dashboard to navigate to another route.
    bridge.navigate('/orders');
  });
</script>

npm install @usethrottle/extension-bridge

// Option B: npm package (React / bundled apps)
import { createBridge } from '@usethrottle/extension-bridge';

const bridge = createBridge({
  targetOrigin: 'https://app.usethrottle.dev',
});

// Await the session handshake
const ctx = await bridge.ready;
console.log('workspace:', ctx.workspace.slug, 'app:', ctx.application.slug);
console.log('environment:', ctx.environment.environmentSlug, 'role:', ctx.role);
console.log('scopes:', ctx.scopes);

// Authenticated REST calls using the pinned extension scopes
const orders = await bridge.api.get('/api/v1/orders?limit=5');
const customer = await bridge.api.get('/api/v1/customers/cust_xxx');

// Mutations (requires the relevant :write scope in the manifest)
await bridge.api.post('/api/v1/orders/ord_xxx/notes', { note: 'Inventory reserved' });

// UI helpers
bridge.resize(600);           // resize the iframe panel
bridge.toast('Done', 'info'); // show a dashboard toast
bridge.navigate('/orders');   // navigate the parent window

// Clean up when the component unmounts
bridge.destroy();

type SessionContext = {
  user: { id: string; email: string };
  workspace: { id: string; slug: string };
  application: { id: string; slug: string };
  environment: {
    environmentId: string;
    environmentSlug: string;
    environmentKind: 'production' | 'non_production';
    providerEnvironment: 'production' | 'sandbox';
  };
  installationId: string;
  extensionId: string;
  version: string;
  role: string;
  scopes: string[];
};

const ctx = await bridge.ready;

// Not included: configSchema, config values, API keys, or webhook signing secrets.
// Fetch config explicitly from an allowed API route or keep it server-side.

// React hook pattern
import { useEffect, useRef, useState } from 'react';
import { createBridge, type Bridge, type SessionContext } from '@usethrottle/extension-bridge';

export function useExtensionBridge() {
  const bridgeRef = useRef<Bridge | null>(null);
  const [ctx, setCtx] = useState<SessionContext | null>(null);

  useEffect(() => {
    const bridge = createBridge({ targetOrigin: 'https://app.usethrottle.dev' });
    bridgeRef.current = bridge;

    bridge.ready.then(setCtx);

    return () => bridge.destroy();
  }, []);

  return { bridge: bridgeRef.current, ctx };
}

// In your extension component:
function InventorySidebar() {
  const { bridge, ctx } = useExtensionBridge();

  useEffect(() => {
    if (!bridge || !ctx) return;
    bridge.api.get('/api/v1/orders?limit=20').then((res: any) => {
      // render orders
    });
  }, [bridge, ctx]);

  return <div>...</div>;
}