veryfront 0.0.49 → 0.0.50

package/dist/integrations/airtable/files/lib/airtable-client.ts

@@ -0,0 +1,244 @@
+import { getAccessToken } from "./token-store.ts";
+
+const AIRTABLE_BASE_URL = "https://api.airtable.com/v0";
+
+interface AirtableResponse<T> {
+  records?: T[];
+  offset?: string;
+}
+
+interface AirtableBase {
+  id: string;
+  name: string;
+  permissionLevel: string;
+}
+
+interface AirtableBaseSchema {
+  tables: Array<{
+    id: string;
+    name: string;
+    primaryFieldId: string;
+    fields: Array<{
+      id: string;
+      name: string;
+      type: string;
+      options?: Record<string, unknown>;
+    }>;
+    views: Array<{
+      id: string;
+      name: string;
+      type: string;
+    }>;
+  }>;
+}
+
+export interface AirtableRecord {
+  id: string;
+  createdTime: string;
+  fields: Record<string, unknown>;
+}
+
+interface AirtableField {
+  id: string;
+  name: string;
+  type: string;
+  options?: Record<string, unknown>;
+}
+
+async function airtableFetch<T>(
+  endpoint: string,
+  options: RequestInit = {},
+): Promise<T> {
+  const token = getAccessToken();
+  if (!token) {
+    throw new Error("Not authenticated with Airtable. Please connect your account.");
+  }
+
+  const response = await fetch(`${AIRTABLE_BASE_URL}${endpoint}`, {
+    ...options,
+    headers: {
+      "Authorization": `Bearer ${token}`,
+      "Content-Type": "application/json",
+      ...options.headers,
+    },
+  });
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({}));
+    throw new Error(
+      `Airtable API error: ${response.status} ${error.error?.message || response.statusText}`,
+    );
+  }
+
+  return response.json();
+}
+
+// Meta API for listing bases
+async function metaFetch<T>(
+  endpoint: string,
+  options: RequestInit = {},
+): Promise<T> {
+  const token = getAccessToken();
+  if (!token) {
+    throw new Error("Not authenticated with Airtable. Please connect your account.");
+  }
+
+  const response = await fetch(`https://api.airtable.com/v0/meta${endpoint}`, {
+    ...options,
+    headers: {
+      "Authorization": `Bearer ${token}`,
+      "Content-Type": "application/json",
+      ...options.headers,
+    },
+  });
+
+  if (!response.ok) {
+    const error = await response.json().catch(() => ({}));
+    throw new Error(
+      `Airtable Meta API error: ${response.status} ${error.error?.message || response.statusText}`,
+    );
+  }
+
+  return response.json();
+}
+
+export async function listBases(): Promise<AirtableBase[]> {
+  const response = await metaFetch<{ bases: AirtableBase[] }>("/bases");
+  return response.bases || [];
+}
+
+export async function getBase(baseId: string): Promise<AirtableBaseSchema> {
+  const response = await metaFetch<AirtableBaseSchema>(`/bases/${baseId}/tables`);
+  return response;
+}
+
+export async function listRecords(
+  baseId: string,
+  tableIdOrName: string,
+  options?: {
+    fields?: string[];
+    filterByFormula?: string;
+    maxRecords?: number;
+    pageSize?: number;
+    sort?: Array<{ field: string; direction: "asc" | "desc" }>;
+    view?: string;
+    offset?: string;
+  },
+): Promise<{ records: AirtableRecord[]; offset?: string }> {
+  const params = new URLSearchParams();
+
+  if (options?.fields) {
+    options.fields.forEach((field) => params.append("fields[]", field));
+  }
+  if (options?.filterByFormula) {
+    params.append("filterByFormula", options.filterByFormula);
+  }
+  if (options?.maxRecords) {
+    params.append("maxRecords", options.maxRecords.toString());
+  }
+  if (options?.pageSize) {
+    params.append("pageSize", options.pageSize.toString());
+  }
+  if (options?.sort) {
+    options.sort.forEach((s, i) => {
+      params.append(`sort[${i}][field]`, s.field);
+      params.append(`sort[${i}][direction]`, s.direction);
+    });
+  }
+  if (options?.view) {
+    params.append("view", options.view);
+  }
+  if (options?.offset) {
+    params.append("offset", options.offset);
+  }
+
+  const queryString = params.toString();
+  const endpoint = `/${baseId}/${encodeURIComponent(tableIdOrName)}${
+    queryString ? `?${queryString}` : ""
+  }`;
+
+  const response = await airtableFetch<AirtableResponse<AirtableRecord>>(endpoint);
+
+  return {
+    records: response.records || [],
+    offset: response.offset,
+  };
+}
+
+export function getRecord(
+  baseId: string,
+  tableIdOrName: string,
+  recordId: string,
+): Promise<AirtableRecord> {
+  return airtableFetch<AirtableRecord>(
+    `/${baseId}/${encodeURIComponent(tableIdOrName)}/${recordId}`,
+  );
+}
+
+export function createRecord(
+  baseId: string,
+  tableIdOrName: string,
+  fields: Record<string, unknown>,
+): Promise<AirtableRecord> {
+  return airtableFetch<AirtableRecord>(
+    `/${baseId}/${encodeURIComponent(tableIdOrName)}`,
+    {
+      method: "POST",
+      body: JSON.stringify({ fields }),
+    },
+  );
+}
+
+export async function createRecords(
+  baseId: string,
+  tableIdOrName: string,
+  records: Array<{ fields: Record<string, unknown> }>,
+): Promise<AirtableRecord[]> {
+  const response = await airtableFetch<{ records: AirtableRecord[] }>(
+    `/${baseId}/${encodeURIComponent(tableIdOrName)}`,
+    {
+      method: "POST",
+      body: JSON.stringify({ records }),
+    },
+  );
+  return response.records;
+}
+
+export function updateRecord(
+  baseId: string,
+  tableIdOrName: string,
+  recordId: string,
+  fields: Record<string, unknown>,
+  options?: { destructive?: boolean },
+): Promise<AirtableRecord> {
+  return airtableFetch<AirtableRecord>(
+    `/${baseId}/${encodeURIComponent(tableIdOrName)}/${recordId}`,
+    {
+      method: options?.destructive ? "PUT" : "PATCH",
+      body: JSON.stringify({ fields }),
+    },
+  );
+}
+
+export function deleteRecord(
+  baseId: string,
+  tableIdOrName: string,
+  recordId: string,
+): Promise<{ id: string; deleted: boolean }> {
+  return airtableFetch<{ id: string; deleted: boolean }>(
+    `/${baseId}/${encodeURIComponent(tableIdOrName)}/${recordId}`,
+    { method: "DELETE" },
+  );
+}
+
+// Helper to format field value for display
+export function formatFieldValue(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (Array.isArray(value)) {
+    return value.map((v) => formatFieldValue(v)).join(", ");
+  }
+  if (typeof value === "object") {
+    return JSON.stringify(value);
+  }
+  return String(value);
+}

package/dist/integrations/airtable/files/lib/token-store.ts

@@ -0,0 +1,5 @@
+/**
+ * Airtable Token Store
+ */
+
+export { memoryTokenStore as tokenStore, type OAuthTokens, type TokenStore } from "veryfront/oauth";

package/dist/integrations/anthropic/README.md

@@ -0,0 +1,181 @@
+# Anthropic Admin Integration
+
+A complete integration with the Anthropic Admin API for organization management, usage tracking, and workspace administration.
+
+## Overview
+
+This integration provides AI-powered tools to interact with the Anthropic Admin API, enabling you to:
+
+- List and manage workspaces
+- Monitor API usage and costs
+- Manage API keys
+- View organization members
+- Access organization settings
+
+## Files Created
+
+### Configuration
+- **connector.json** - Integration metadata with setup guide
+- **files/_env.example** - Environment variable template
+
+### API Client
+- **files/lib/anthropic-admin-client.ts** - Fully typed TypeScript client for Anthropic Admin API
+  - `AnthropicAdminClient` class with methods for all API endpoints
+  - Strong TypeScript interfaces for all response types
+  - Comprehensive error handling with custom `AnthropicAdminError`
+  - Singleton pattern with `getAnthropicAdminClient()`
+
+### AI Tools
+All tools use `import { tool } from 'veryfront/ai'` and Zod schemas:
+
+- **files/ai/tools/list-workspaces.ts** - List all workspaces in the organization
+- **files/ai/tools/get-usage.ts** - Get API usage statistics with filtering options
+- **files/ai/tools/list-api-keys.ts** - List API keys for organization or workspace
+- **files/ai/tools/list-members.ts** - List organization members with role breakdown
+- **files/ai/tools/get-organization.ts** - Get organization details and settings
+
+## Setup
+
+1. Get an admin API key from https://console.anthropic.com
+2. Add to your `.env` file:
+   ```
+   ANTHROPIC_ADMIN_API_KEY=sk-ant-admin-your-key-here
+   ```
+
+3. Install the integration via Veryfront CLI (when available)
+
+## API Client Features
+
+### Strong TypeScript Types
+
+```typescript
+interface AnthropicWorkspace {
+  id: string;
+  name: string;
+  display_name: string;
+  created_at: string;
+}
+
+interface AnthropicUsageRecord {
+  workspace_id: string;
+  date: string;
+  model: string;
+  input_tokens: number;
+  output_tokens: number;
+  cache_creation_tokens?: number;
+  cache_read_tokens?: number;
+  total_cost_usd: number;
+}
+```
+
+### Error Handling
+
+Custom `AnthropicAdminError` class with:
+- Error message
+- HTTP status code
+- Raw API response
+
+### Usage Examples
+
+```typescript
+import { getAnthropicAdminClient } from './lib/anthropic-admin-client';
+
+// List workspaces
+const client = getAnthropicAdminClient();
+const { workspaces } = await client.listWorkspaces();
+
+// Get usage for date range
+const usage = await client.getUsage({
+  startDate: '2025-01-01',
+  endDate: '2025-01-31',
+  workspaceId: 'ws-123',
+  model: 'claude-3-opus-20240229',
+  granularity: 'day'
+});
+
+// List API keys
+const { api_keys } = await client.listAPIKeys('ws-123');
+
+// Get organization details
+const org = await client.getOrganization();
+```
+
+## AI Tools Features
+
+All tools return structured responses with:
+- `success` boolean
+- `message` string description
+- Relevant data fields
+- Error information on failure
+- Summary statistics where applicable
+
+### Example Tool Response
+
+```typescript
+{
+  success: true,
+  usage: [...],
+  summary: {
+    total_cost_usd: 45.67,
+    total_input_tokens: 123456,
+    total_output_tokens: 78901,
+    record_count: 31,
+    date_range: {
+      start: '2025-01-01',
+      end: '2025-01-31'
+    }
+  },
+  message: "Retrieved 31 usage record(s) totaling $45.67 USD"
+}
+```
+
+## Authentication
+
+This integration uses API key authentication. No OAuth flow required.
+
+- Admin keys provide full access to organization management
+- Keys should start with `sk-ant-`
+- Store securely and never commit to version control
+
+## Security Considerations
+
+- Admin API keys have full organization access
+- Consider using workspace-specific keys with limited permissions for production
+- Keys can be revoked at any time via the Anthropic Console
+- The API client validates key format on initialization
+
+## Rate Limits
+
+All endpoints are subject to Anthropic's rate limits. See https://docs.anthropic.com/en/api/rate-limits
+
+## Documentation
+
+Official Anthropic Admin API docs: https://docs.anthropic.com/en/api/admin-api
+
+## Directory Structure
+
+```
+anthropic/
+├── connector.json                    # Integration metadata
+├── README.md                         # This file
+└── files/
+    ├── _env.example                  # Environment template
+    ├── lib/
+    │   └── anthropic-admin-client.ts # API client
+    └── ai/
+        └── tools/
+            ├── list-workspaces.ts    # Workspace listing
+            ├── get-usage.ts          # Usage statistics
+            ├── list-api-keys.ts      # API key management
+            ├── list-members.ts       # Member listing
+            └── get-organization.ts   # Organization details
+```
+
+## TypeScript Features
+
+- Strict type checking throughout
+- Comprehensive interfaces for all API responses
+- Generic request method with type parameters
+- Proper error type guards
+- TSDoc comments for all public methods
+- Utility types for optional parameters

package/dist/integrations/anthropic/connector.json

@@ -0,0 +1,88 @@
+{
+  "name": "anthropic",
+  "displayName": "Anthropic",
+  "description": "Integrate with Anthropic Admin API to manage workspaces, monitor usage, and access organization data",
+  "auth": {
+    "type": "api-key",
+    "envVars": {
+      "ANTHROPIC_ADMIN_API_KEY": {
+        "description": "Admin API key for Anthropic organization management",
+        "required": true
+      }
+    }
+  },
+  "tools": [
+    {
+      "name": "list-workspaces",
+      "description": "List all workspaces in the organization"
+    },
+    {
+      "name": "get-usage",
+      "description": "Get API usage statistics for a date range"
+    },
+    {
+      "name": "list-api-keys",
+      "description": "List API keys for a workspace or organization"
+    },
+    {
+      "name": "list-members",
+      "description": "List all members in the organization"
+    },
+    {
+      "name": "get-organization",
+      "description": "Get organization details and settings"
+    }
+  ],
+  "SETUP_GUIDE": {
+    "title": "Anthropic Admin API Setup",
+    "steps": [
+      {
+        "step": 1,
+        "title": "Access Anthropic Console",
+        "description": "Go to https://console.anthropic.com and sign in to your organization account"
+      },
+      {
+        "step": 2,
+        "title": "Navigate to Organization Settings",
+        "description": "Click on your organization name in the top-right corner, then select 'Organization Settings'"
+      },
+      {
+        "step": 3,
+        "title": "Go to API Keys",
+        "description": "In the left sidebar, click on 'API Keys' under the Organization section"
+      },
+      {
+        "step": 4,
+        "title": "Create Admin API Key",
+        "description": "Click 'Create API Key' and select 'Admin' as the key type. Admin keys have full access to organization management features including workspaces, usage data, members, and API key management"
+      },
+      {
+        "step": 5,
+        "title": "Name Your Key",
+        "description": "Give your key a descriptive name (e.g., 'Veryfront Admin Integration') to identify its purpose"
+      },
+      {
+        "step": 6,
+        "title": "Copy and Secure Your Key",
+        "description": "Copy the API key immediately after creation. This is the only time you'll be able to see the full key. Store it securely - you'll need it for the ANTHROPIC_ADMIN_API_KEY environment variable"
+      },
+      {
+        "step": 7,
+        "title": "Set Environment Variable",
+        "description": "Add the API key to your .env file: ANTHROPIC_ADMIN_API_KEY=sk-ant-admin-***"
+      },
+      {
+        "step": 8,
+        "title": "Verify Access",
+        "description": "Test the integration by calling the get-organization tool to confirm your admin key has the correct permissions"
+      }
+    ],
+    "notes": [
+      "Admin API keys have full access to organization management features. Keep them secure and never commit them to version control",
+      "For production use, consider using workspace-specific keys with limited permissions where appropriate",
+      "You can revoke API keys at any time from the Anthropic Console",
+      "Rate limits apply to all API endpoints. See https://docs.anthropic.com/en/api/rate-limits for details"
+    ],
+    "documentation": "https://docs.anthropic.com/en/api/admin-api"
+  }
+}

package/dist/integrations/anthropic/files/_env.example

@@ -0,0 +1,4 @@
+# Anthropic Admin API Configuration
+# Get your admin API key from https://console.anthropic.com
+# Admin keys provide full access to organization management features
+ANTHROPIC_ADMIN_API_KEY=sk-ant-admin-your-api-key-here

package/dist/integrations/anthropic/files/ai/tools/get-organization.ts

@@ -0,0 +1,36 @@
+import { tool } from 'veryfront/ai';
+import { z } from 'zod';
+import { getAnthropicAdminClient } from '../../lib/anthropic-admin-client';
+
+/**
+ * Tool for retrieving Anthropic organization details
+ */
+export const getOrganization = tool({
+  name: 'get_organization',
+  description:
+    'Get detailed information about the Anthropic organization including name, settings, default configurations, and billing information.',
+  parameters: z.object({}),
+  execute: async () => {
+    try {
+      const client = getAnthropicAdminClient();
+      const organization = await client.getOrganization();
+
+      return {
+        success: true,
+        organization,
+        message: `Retrieved organization details for ${organization.display_name}`,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error:
+          error instanceof Error
+            ? error.message
+            : 'Failed to retrieve organization details',
+        organization: null,
+      };
+    }
+  },
+});
+
+export default getOrganization;

package/dist/integrations/anthropic/files/ai/tools/get-usage.ts

@@ -0,0 +1,100 @@
+import { tool } from 'veryfront/ai';
+import { z } from 'zod';
+import { getAnthropicAdminClient } from '../../lib/anthropic-admin-client';
+
+/**
+ * Tool for retrieving API usage statistics from Anthropic
+ */
+export const getUsage = tool({
+  name: 'get_usage',
+  description:
+    'Get API usage statistics for a specific date range. Returns token usage and costs broken down by date, workspace, and model. Dates must be in YYYY-MM-DD format.',
+  parameters: z.object({
+    startDate: z
+      .string()
+      .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in YYYY-MM-DD format')
+      .describe('Start date for usage query (YYYY-MM-DD format, e.g., 2025-01-01)'),
+    endDate: z
+      .string()
+      .regex(/^\d{4}-\d{2}-\d{2}$/, 'Date must be in YYYY-MM-DD format')
+      .describe('End date for usage query (YYYY-MM-DD format, e.g., 2025-01-31)'),
+    workspaceId: z
+      .string()
+      .optional()
+      .describe(
+        'Optional workspace ID to filter usage by specific workspace'
+      ),
+    model: z
+      .string()
+      .optional()
+      .describe(
+        'Optional model name to filter usage (e.g., claude-3-opus-20240229, claude-3-sonnet-20240229)'
+      ),
+    granularity: z
+      .enum(['day', 'hour'])
+      .default('day')
+      .describe('Time granularity for usage aggregation (day or hour)'),
+  }),
+  execute: async ({ startDate, endDate, workspaceId, model, granularity }) => {
+    try {
+      const client = getAnthropicAdminClient();
+      const result = await client.getUsage({
+        startDate,
+        endDate,
+        workspaceId,
+        model,
+        granularity,
+      });
+
+      // Calculate summary statistics
+      const totalInputTokens = result.usage.reduce(
+        (sum, record) => sum + record.input_tokens,
+        0
+      );
+      const totalOutputTokens = result.usage.reduce(
+        (sum, record) => sum + record.output_tokens,
+        0
+      );
+      const totalCacheCreationTokens = result.usage.reduce(
+        (sum, record) => sum + (record.cache_creation_tokens || 0),
+        0
+      );
+      const totalCacheReadTokens = result.usage.reduce(
+        (sum, record) => sum + (record.cache_read_tokens || 0),
+        0
+      );
+
+      return {
+        success: true,
+        usage: result.usage,
+        summary: {
+          total_cost_usd: result.total_cost_usd,
+          total_input_tokens: totalInputTokens,
+          total_output_tokens: totalOutputTokens,
+          total_cache_creation_tokens: totalCacheCreationTokens,
+          total_cache_read_tokens: totalCacheReadTokens,
+          record_count: result.usage.length,
+          date_range: {
+            start: startDate,
+            end: endDate,
+          },
+          filters: {
+            workspace_id: workspaceId,
+            model,
+            granularity,
+          },
+        },
+        message: `Retrieved ${result.usage.length} usage record(s) totaling $${result.total_cost_usd.toFixed(4)} USD`,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error:
+          error instanceof Error ? error.message : 'Failed to retrieve usage data',
+        usage: [],
+      };
+    }
+  },
+});
+
+export default getUsage;