diff --git a/.agents/skills/add-block/SKILL.md b/.agents/skills/add-block/SKILL.md index 0133b14e14f..c475f27eda8 100644 --- a/.agents/skills/add-block/SKILL.md +++ b/.agents/skills/add-block/SKILL.md @@ -19,7 +19,7 @@ When the user asks you to create a block: ```typescript import { {ServiceName}Icon } from '@/components/icons' import type { BlockConfig } from '@/blocks/types' -import { AuthMode } from '@/blocks/types' +import { AuthMode, IntegrationType } from '@/blocks/types' import { getScopesForService } from '@/lib/oauth/utils' export const {ServiceName}Block: BlockConfig = { @@ -29,6 +29,8 @@ export const {ServiceName}Block: BlockConfig = { longDescription: 'Detailed description for docs', docsLink: 'https://docs.sim.ai/tools/{service}', category: 'tools', // 'tools' | 'blocks' | 'triggers' + integrationType: IntegrationType.X, // Primary category (see IntegrationType enum) + tags: ['oauth', 'api'], // Cross-cutting tags (see IntegrationTag type) bgColor: '#HEXCOLOR', // Brand color icon: {ServiceName}Icon, @@ -629,7 +631,7 @@ export const registry: Record = { ```typescript import { ServiceIcon } from '@/components/icons' import type { BlockConfig } from '@/blocks/types' -import { AuthMode } from '@/blocks/types' +import { AuthMode, IntegrationType } from '@/blocks/types' import { getScopesForService } from '@/lib/oauth/utils' export const ServiceBlock: BlockConfig = { @@ -639,6 +641,8 @@ export const ServiceBlock: BlockConfig = { longDescription: 'Full description for documentation...', docsLink: 'https://docs.sim.ai/tools/service', category: 'tools', + integrationType: IntegrationType.DeveloperTools, + tags: ['oauth', 'api'], bgColor: '#FF6B6B', icon: ServiceIcon, authMode: AuthMode.OAuth, @@ -796,6 +800,8 @@ All tool IDs referenced in `tools.access` and returned by `tools.config.tool` MU ## Checklist Before Finishing +- [ ] `integrationType` is set to the correct `IntegrationType` enum value +- [ ] `tags` array includes all applicable `IntegrationTag` values - [ ] All subBlocks have `id`, `title` (except switch), and `type` - [ ] Conditions use correct syntax (field, value, not, and) - [ ] DependsOn set for fields that need other values diff --git a/.agents/skills/add-tools/SKILL.md b/.agents/skills/add-tools/SKILL.md index 66f6f88d047..03dbd68456f 100644 --- a/.agents/skills/add-tools/SKILL.md +++ b/.agents/skills/add-tools/SKILL.md @@ -266,9 +266,9 @@ export * from './types' ## Registering Tools -After creating tools, remind the user to: +After creating tools: 1. Import tools in `apps/sim/tools/registry.ts` -2. Add to the `tools` object with snake_case keys: +2. Add to the `tools` object with snake_case keys (alphabetically): ```typescript import { serviceActionTool } from '@/tools/{service}' @@ -278,6 +278,130 @@ export const tools = { } ``` +## Wiring Tools into the Block (Required) + +After registering in `tools/registry.ts`, you MUST also update the block definition at `apps/sim/blocks/blocks/{service}.ts`. This is not optional — tools are only usable from the UI if they are wired into the block. + +### 1. Add to `tools.access` + +```typescript +tools: { + access: [ + // existing tools... + 'service_new_action', // Add every new tool ID here + ], + config: { ... } +} +``` + +### 2. Add operation dropdown options + +If the block uses an operation dropdown, add an option for each new tool: + +```typescript +{ + id: 'operation', + type: 'dropdown', + options: [ + // existing options... + { label: 'New Action', id: 'new_action' }, // id maps to what tools.config.tool returns + ], +} +``` + +### 3. Add subBlocks for new tool params + +For each new tool, add subBlocks covering all its required params (and optional ones where useful). Apply `condition` to show them only for the right operation, and mark required params with `required`: + +```typescript +// Required param for new_action +{ + id: 'someParam', + title: 'Some Param', + type: 'short-input', + placeholder: 'e.g., value', + condition: { field: 'operation', value: 'new_action' }, + required: { field: 'operation', value: 'new_action' }, +}, +// Optional param — put in advanced mode +{ + id: 'optionalParam', + title: 'Optional Param', + type: 'short-input', + condition: { field: 'operation', value: 'new_action' }, + mode: 'advanced', +}, +``` + +### 4. Update `tools.config.tool` + +Ensure the tool selector returns the correct tool ID for every new operation. The simplest pattern: + +```typescript +tool: (params) => `service_${params.operation}`, +// If operation dropdown IDs already match tool IDs, this requires no change. +``` + +If the dropdown IDs differ from tool IDs, add explicit mappings: + +```typescript +tool: (params) => { + const map: Record = { + new_action: 'service_new_action', + // ... + } + return map[params.operation] ?? `service_${params.operation}` +}, +``` + +### 5. Update `tools.config.params` + +Add any type coercions needed for new params (runs at execution time, after variable resolution): + +```typescript +params: (params) => { + const result: Record = {} + if (params.limit != null && params.limit !== '') result.limit = Number(params.limit) + if (params.newParamName) result.toolParamName = params.newParamName // rename if IDs differ + return result +}, +``` + +### 6. Add new outputs + +Add any new fields returned by the new tools to the block `outputs`: + +```typescript +outputs: { + // existing outputs... + newField: { type: 'string', description: 'Description of new field' }, +} +``` + +### 7. Add new inputs + +Add new subBlock param IDs to the block `inputs` section: + +```typescript +inputs: { + // existing inputs... + someParam: { type: 'string', description: 'Param description' }, + optionalParam: { type: 'string', description: 'Optional param description' }, +} +``` + +### Block wiring checklist + +- [ ] New tool IDs added to `tools.access` +- [ ] Operation dropdown has an option for each new tool +- [ ] SubBlocks cover all required params for each new tool +- [ ] SubBlocks have correct `condition` (only show for the right operation) +- [ ] Optional/rarely-used params set to `mode: 'advanced'` +- [ ] `tools.config.tool` returns correct ID for every new operation +- [ ] `tools.config.params` handles any ID remapping or type coercions +- [ ] New outputs added to block `outputs` +- [ ] New params added to block `inputs` + ## V2 Tool Pattern If creating V2 tools (API-aligned outputs), use `_v2` suffix: @@ -299,7 +423,9 @@ All tool IDs MUST use `snake_case`: `{service}_{action}` (e.g., `x_create_tweet` - [ ] All optional outputs have `optional: true` - [ ] No raw JSON dumps in outputs - [ ] Types file has all interfaces -- [ ] Index.ts exports all tools +- [ ] Index.ts exports all tools and re-exports types (`export * from './types'`) +- [ ] Tools registered in `tools/registry.ts` +- [ ] Block wired: `tools.access`, dropdown options, subBlocks, `tools.config`, outputs, inputs ## Final Validation (Required) diff --git a/.agents/skills/you-might-not-need-an-effect/SKILL.md b/.agents/skills/you-might-not-need-an-effect/SKILL.md new file mode 100644 index 00000000000..09aacedc8bc --- /dev/null +++ b/.agents/skills/you-might-not-need-an-effect/SKILL.md @@ -0,0 +1,17 @@ +--- +name: you-might-not-need-an-effect +description: Analyze and fix useEffect anti-patterns in your code +--- + +# You Might Not Need an Effect + +Arguments: +- scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase" +- fix: whether to apply fixes (default: true). Set to false to only propose changes. + +User arguments: $ARGUMENTS + +Steps: +1. Read https://react.dev/learn/you-might-not-need-an-effect to understand the guidelines +2. Analyze the specified scope for useEffect anti-patterns +3. If fix=true, apply the fixes. If fix=false, propose the fixes without applying. diff --git a/.claude/commands/add-connector.md b/.claude/commands/add-connector.md index 4635211ffe7..22c8c52e1c8 100644 --- a/.claude/commands/add-connector.md +++ b/.claude/commands/add-connector.md @@ -71,12 +71,14 @@ export const {service}Connector: ConnectorConfig = { ], listDocuments: async (accessToken, sourceConfig, cursor) => { - // Paginate via cursor, extract text, compute SHA-256 hash + // Return metadata stubs with contentDeferred: true (if per-doc content fetch needed) + // Or full documents with content (if list API returns content inline) // Return { documents: ExternalDocument[], nextCursor?, hasMore } }, getDocument: async (accessToken, sourceConfig, externalId) => { - // Return ExternalDocument or null + // Fetch full content for a single document + // Return ExternalDocument with contentDeferred: false, or null }, validateConfig: async (accessToken, sourceConfig) => { @@ -281,26 +283,110 @@ Every document returned from `listDocuments`/`getDocument` must include: { externalId: string // Source-specific unique ID title: string // Document title - content: string // Extracted plain text + content: string // Extracted plain text (or '' if contentDeferred) + contentDeferred?: boolean // true = content will be fetched via getDocument mimeType: 'text/plain' // Always text/plain (content is extracted) - contentHash: string // SHA-256 of content (change detection) + contentHash: string // Metadata-based hash for change detection sourceUrl?: string // Link back to original (stored on document record) metadata?: Record // Source-specific data (fed to mapTags) } ``` -## Content Hashing (Required) +## Content Deferral (Required for file/content-download connectors) -The sync engine uses content hashes for change detection: +**All connectors that require per-document API calls to fetch content MUST use `contentDeferred: true`.** This is the standard pattern — `listDocuments` returns lightweight metadata stubs, and content is fetched lazily by the sync engine via `getDocument` only for new/changed documents. + +This pattern is critical for reliability: the sync engine processes documents in batches and enqueues each batch for processing immediately. If a sync times out, all previously-batched documents are already queued. Without deferral, content downloads during listing can exhaust the sync task's time budget before any documents are saved. + +### When to use `contentDeferred: true` + +- The service's list API does NOT return document content (only metadata) +- Content requires a separate download/export API call per document +- Examples: Google Drive, OneDrive, SharePoint, Dropbox, Notion, Confluence, Gmail, Obsidian, Evernote, GitHub + +### When NOT to use `contentDeferred` + +- The list API already returns the full content inline (e.g., Slack messages, Reddit posts, HubSpot notes) +- No per-document API call is needed to get content + +### Content Hash Strategy + +Use a **metadata-based** `contentHash` — never a content-based hash. The hash must be derivable from the list response metadata alone, so the sync engine can detect changes without downloading content. + +Good metadata hash sources: +- `modifiedTime` / `lastModifiedDateTime` — changes when file is edited +- Git blob SHA — unique per content version +- API-provided content hash (e.g., Dropbox `content_hash`) +- Version number (e.g., Confluence page version) + +Format: `{service}:{id}:{changeIndicator}` ```typescript -async function computeContentHash(content: string): Promise { - const data = new TextEncoder().encode(content) - const hashBuffer = await crypto.subtle.digest('SHA-256', data) - return Array.from(new Uint8Array(hashBuffer)).map(b => b.toString(16).padStart(2, '0')).join('') +// Google Drive: modifiedTime changes on edit +contentHash: `gdrive:${file.id}:${file.modifiedTime ?? ''}` + +// GitHub: blob SHA is a content-addressable hash +contentHash: `gitsha:${item.sha}` + +// Dropbox: API provides content_hash +contentHash: `dropbox:${entry.id}:${entry.content_hash ?? entry.server_modified}` + +// Confluence: version number increments on edit +contentHash: `confluence:${page.id}:${page.version.number}` +``` + +**Critical invariant:** The `contentHash` MUST be identical whether produced by `listDocuments` (stub) or `getDocument` (full doc). Both should use the same stub function to guarantee this. + +### Implementation Pattern + +```typescript +// 1. Create a stub function (sync, no API calls) +function fileToStub(file: ServiceFile): ExternalDocument { + return { + externalId: file.id, + title: file.name || 'Untitled', + content: '', + contentDeferred: true, + mimeType: 'text/plain', + sourceUrl: `https://service.com/file/${file.id}`, + contentHash: `service:${file.id}:${file.modifiedTime ?? ''}`, + metadata: { /* fields needed by mapTags */ }, + } +} + +// 2. listDocuments returns stubs (fast, metadata only) +listDocuments: async (accessToken, sourceConfig, cursor) => { + const response = await fetchWithRetry(listUrl, { ... }) + const files = (await response.json()).files + const documents = files.map(fileToStub) + return { documents, nextCursor, hasMore } +} + +// 3. getDocument fetches content and returns full doc with SAME contentHash +getDocument: async (accessToken, sourceConfig, externalId) => { + const metadata = await fetchWithRetry(metadataUrl, { ... }) + const file = await metadata.json() + if (file.trashed) return null + + try { + const content = await fetchContent(accessToken, file) + if (!content.trim()) return null + const stub = fileToStub(file) + return { ...stub, content, contentDeferred: false } + } catch (error) { + logger.warn(`Failed to fetch content for: ${file.name}`, { error }) + return null + } } ``` +### Reference Implementations + +- **Google Drive**: `connectors/google-drive/google-drive.ts` — file download/export with `modifiedTime` hash +- **GitHub**: `connectors/github/github.ts` — git blob SHA hash +- **Notion**: `connectors/notion/notion.ts` — blocks API with `last_edited_time` hash +- **Confluence**: `connectors/confluence/confluence.ts` — version number hash + ## tagDefinitions — Declared Tag Definitions Declare which tags the connector populates using semantic IDs. Shown in the add-connector modal as opt-out checkboxes. @@ -409,7 +495,10 @@ export const CONNECTOR_REGISTRY: ConnectorRegistry = { ## Reference Implementations -- **OAuth**: `apps/sim/connectors/confluence/confluence.ts` — multiple config field types, `mapTags`, label fetching +- **OAuth + contentDeferred**: `apps/sim/connectors/google-drive/google-drive.ts` — file download with metadata-based hash, `orderBy` for deterministic pagination +- **OAuth + contentDeferred (blocks API)**: `apps/sim/connectors/notion/notion.ts` — complex block content extraction deferred to `getDocument` +- **OAuth + contentDeferred (git)**: `apps/sim/connectors/github/github.ts` — blob SHA hash, tree listing +- **OAuth + inline content**: `apps/sim/connectors/confluence/confluence.ts` — multiple config field types, `mapTags`, label fetching - **API key**: `apps/sim/connectors/fireflies/fireflies.ts` — GraphQL API with Bearer token auth ## Checklist @@ -425,7 +514,9 @@ export const CONNECTOR_REGISTRY: ConnectorRegistry = { - `selectorKey` exists in `hooks/selectors/registry.ts` - `dependsOn` references selector field IDs (not `canonicalParamId`) - Dependency `canonicalParamId` values exist in `SELECTOR_CONTEXT_FIELDS` -- [ ] `listDocuments` handles pagination and computes content hashes +- [ ] `listDocuments` handles pagination with metadata-based content hashes +- [ ] `contentDeferred: true` used if content requires per-doc API calls (file download, export, blocks fetch) +- [ ] `contentHash` is metadata-based (not content-based) and identical between stub and `getDocument` - [ ] `sourceUrl` set on each ExternalDocument (full URL, not relative) - [ ] `metadata` includes source-specific data for tag mapping - [ ] `tagDefinitions` declared for each semantic key returned by `mapTags` diff --git a/.claude/commands/add-hosted-key.md b/.claude/commands/add-hosted-key.md new file mode 100644 index 00000000000..14daa42032e --- /dev/null +++ b/.claude/commands/add-hosted-key.md @@ -0,0 +1,296 @@ +--- +description: Add hosted API key support to a tool so Sim provides the key when users don't bring their own +argument-hint: +--- + +# Adding Hosted Key Support to a Tool + +When a tool has hosted key support, Sim provides its own API key if the user hasn't configured one (via BYOK or env var). Usage is metered and billed to the workspace. + +## Overview + +| Step | What | Where | +|------|------|-------| +| 1 | Register BYOK provider ID | `tools/types.ts`, `app/api/workspaces/[id]/byok-keys/route.ts` | +| 2 | Research the API's pricing and rate limits | API docs / pricing page (before writing any code) | +| 3 | Add `hosting` config to the tool | `tools/{service}/{action}.ts` | +| 4 | Hide API key field when hosted | `blocks/blocks/{service}.ts` | +| 5 | Add to BYOK settings UI | BYOK settings component (`byok.tsx`) | +| 6 | Summarize pricing and throttling comparison | Output to user (after all code changes) | + +## Step 1: Register the BYOK Provider ID + +Add the new provider to the `BYOKProviderId` union in `tools/types.ts`: + +```typescript +export type BYOKProviderId = + | 'openai' + | 'anthropic' + // ...existing providers + | 'your_service' +``` + +Then add it to `VALID_PROVIDERS` in `app/api/workspaces/[id]/byok-keys/route.ts`: + +```typescript +const VALID_PROVIDERS = ['openai', 'anthropic', 'google', 'mistral', 'your_service'] as const +``` + +## Step 2: Research the API's Pricing Model and Rate Limits + +**Before writing any `getCost` or `rateLimit` code**, look up the service's official documentation for both pricing and rate limits. You need to understand: + +### Pricing + +1. **How the API charges** — per request, per credit, per token, per step, per minute, etc. +2. **Whether the API reports cost in its response** — look for fields like `creditsUsed`, `costDollars`, `tokensUsed`, or similar in the response body or headers +3. **Whether cost varies by endpoint/options** — some APIs charge more for certain features (e.g., Firecrawl charges 1 credit/page base but +4 for JSON format, +4 for enhanced mode) +4. **The dollar-per-unit rate** — what each credit/token/unit costs in dollars on our plan + +### Rate Limits + +1. **What rate limits the API enforces** — requests per minute/second, tokens per minute, concurrent requests, etc. +2. **Whether limits vary by plan tier** — free vs paid vs enterprise often have different ceilings +3. **Whether limits are per-key or per-account** — determines whether adding more hosted keys actually increases total throughput +4. **What the API returns when rate limited** — HTTP 429, `Retry-After` header, error body format, etc. +5. **Whether there are multiple dimensions** — some APIs limit both requests/min AND tokens/min independently + +Search the API's docs/pricing page (use WebSearch/WebFetch). Capture the pricing model as a comment in `getCost` so future maintainers know the source of truth. + +### Setting Our Rate Limits + +Our rate limiter (`lib/core/rate-limiter/hosted-key/`) uses a token-bucket algorithm applied **per billing actor** (workspace). It supports two modes: + +- **`per_request`** — simple; just `requestsPerMinute`. Good when the API charges flat per-request or cost doesn't vary much. +- **`custom`** — `requestsPerMinute` plus additional `dimensions` (e.g., `tokens`, `search_units`). Each dimension has its own `limitPerMinute` and an `extractUsage` function that reads actual usage from the response. Use when the API charges on a variable metric (tokens, credits) and you want to cap that metric too. + +When choosing values for `requestsPerMinute` and any dimension limits: + +- **Stay well below the API's per-key limit** — our keys are shared across all workspaces. If the API allows 60 RPM per key and we have 3 keys, the global ceiling is ~180 RPM. Set the per-workspace limit low enough (e.g., 20-60 RPM) that many workspaces can coexist without collectively hitting the API's ceiling. +- **Account for key pooling** — our round-robin distributes requests across `N` hosted keys, so the effective API-side rate per key is `(total requests) / N`. But per-workspace limits are enforced *before* key selection, so they apply regardless of key count. +- **Prefer conservative defaults** — it's easy to raise limits later but hard to claw back after users depend on high throughput. + +## Step 3: Add `hosting` Config to the Tool + +Add a `hosting` object to the tool's `ToolConfig`. This tells the execution layer how to acquire hosted keys, calculate cost, and rate-limit. + +```typescript +hosting: { + envKeyPrefix: 'YOUR_SERVICE_API_KEY', + apiKeyParam: 'apiKey', + byokProviderId: 'your_service', + pricing: { + type: 'custom', + getCost: (_params, output) => { + if (output.creditsUsed == null) { + throw new Error('Response missing creditsUsed field') + } + const creditsUsed = output.creditsUsed as number + const cost = creditsUsed * 0.001 // dollars per credit + return { cost, metadata: { creditsUsed } } + }, + }, + rateLimit: { + mode: 'per_request', + requestsPerMinute: 100, + }, +}, +``` + +### Hosted Key Env Var Convention + +Keys use a numbered naming pattern driven by a count env var: + +``` +YOUR_SERVICE_API_KEY_COUNT=3 +YOUR_SERVICE_API_KEY_1=sk-... +YOUR_SERVICE_API_KEY_2=sk-... +YOUR_SERVICE_API_KEY_3=sk-... +``` + +The `envKeyPrefix` value (`YOUR_SERVICE_API_KEY`) determines which env vars are read at runtime. Adding more keys only requires bumping the count and adding the new env var. + +### Pricing: Prefer API-Reported Cost + +Always prefer using cost data returned by the API (e.g., `creditsUsed`, `costDollars`). This is the most accurate because it accounts for variable pricing tiers, feature modifiers, and plan-level discounts. + +**When the API reports cost** — use it directly and throw if missing: + +```typescript +pricing: { + type: 'custom', + getCost: (params, output) => { + if (output.creditsUsed == null) { + throw new Error('Response missing creditsUsed field') + } + // $0.001 per credit — from https://example.com/pricing + const cost = (output.creditsUsed as number) * 0.001 + return { cost, metadata: { creditsUsed: output.creditsUsed } } + }, +}, +``` + +**When the API does NOT report cost** — compute it from params/output based on the pricing docs, but still validate the data you depend on: + +```typescript +pricing: { + type: 'custom', + getCost: (params, output) => { + if (!Array.isArray(output.searchResults)) { + throw new Error('Response missing searchResults, cannot determine cost') + } + // Serper: 1 credit for <=10 results, 2 credits for >10 — from https://serper.dev/pricing + const credits = Number(params.num) > 10 ? 2 : 1 + return { cost: credits * 0.001, metadata: { credits } } + }, +}, +``` + +**`getCost` must always throw** if it cannot determine cost. Never silently fall back to a default — this would hide billing inaccuracies. + +### Capturing Cost Data from the API + +If the API returns cost info, capture it in `transformResponse` so `getCost` can read it from the output: + +```typescript +transformResponse: async (response: Response) => { + const data = await response.json() + return { + success: true, + output: { + results: data.results, + creditsUsed: data.creditsUsed, // pass through for getCost + }, + } +}, +``` + +For async/polling tools, capture it in `postProcess` when the job completes: + +```typescript +if (jobData.status === 'completed') { + result.output = { + data: jobData.data, + creditsUsed: jobData.creditsUsed, + } +} +``` + +## Step 4: Hide the API Key Field When Hosted + +In the block config (`blocks/blocks/{service}.ts`), add `hideWhenHosted: true` to the API key subblock. This hides the field on hosted Sim since the platform provides the key: + +```typescript +{ + id: 'apiKey', + title: 'API Key', + type: 'short-input', + placeholder: 'Enter your API key', + password: true, + required: true, + hideWhenHosted: true, +}, +``` + +The visibility is controlled by `isSubBlockHidden()` in `lib/workflows/subblocks/visibility.ts`, which checks both the `isHosted` feature flag (`hideWhenHosted`) and optional env var conditions (`hideWhenEnvSet`). + +### Excluding Specific Operations from Hosted Key Support + +When a block has multiple operations but some operations should **not** use a hosted key (e.g., the underlying API is deprecated, unsupported, or too expensive), use the **duplicate apiKey subblock** pattern. This is the same pattern Exa uses for its `research` operation: + +1. **Remove the `hosting` config** from the tool definition for that operation — it must not have a `hosting` object at all. +2. **Duplicate the `apiKey` subblock** in the block config with opposing conditions: + +```typescript +// API Key — hidden when hosted for operations with hosted key support +{ + id: 'apiKey', + title: 'API Key', + type: 'short-input', + placeholder: 'Enter your API key', + password: true, + required: true, + hideWhenHosted: true, + condition: { field: 'operation', value: 'unsupported_op', not: true }, +}, +// API Key — always visible for unsupported_op (no hosted key support) +{ + id: 'apiKey', + title: 'API Key', + type: 'short-input', + placeholder: 'Enter your API key', + password: true, + required: true, + condition: { field: 'operation', value: 'unsupported_op' }, +}, +``` + +Both subblocks share the same `id: 'apiKey'`, so the same value flows to the tool. The conditions ensure only one is visible at a time. The first has `hideWhenHosted: true` and shows for all hosted operations; the second has no `hideWhenHosted` and shows only for the excluded operation — meaning users must always provide their own key for that operation. + +To exclude multiple operations, use an array: `{ field: 'operation', value: ['op_a', 'op_b'] }`. + +**Reference implementations:** +- **Exa** (`blocks/blocks/exa.ts`): `research` operation excluded from hosting — lines 309-329 +- **Google Maps** (`blocks/blocks/google_maps.ts`): `speed_limits` operation excluded from hosting (deprecated Roads API) + +## Step 5: Add to the BYOK Settings UI + +Add an entry to the `PROVIDERS` array in the BYOK settings component so users can bring their own key. You need the service icon from `components/icons.tsx`: + +```typescript +{ + id: 'your_service', + name: 'Your Service', + icon: YourServiceIcon, + description: 'What this service does', + placeholder: 'Enter your API key', +}, +``` + +## Step 6: Summarize Pricing and Throttling Comparison + +After all code changes are complete, output a detailed summary to the user covering: + +### What to include + +1. **API's pricing model** — how the service charges (per token, per credit, per request, etc.), the specific rates found in docs, and whether the API reports cost in responses. +2. **Our `getCost` approach** — how we calculate cost, what fields we depend on, and any assumptions or estimates (especially when the API doesn't report exact dollar cost). +3. **API's rate limits** — the documented limits (RPM, TPM, concurrent, etc.), which plan tier they apply to, and whether they're per-key or per-account. +4. **Our `rateLimit` config** — what we set for `requestsPerMinute` (and dimensions if custom mode), why we chose those values, and how they compare to the API's limits. +5. **Key pooling impact** — how many hosted keys we expect, and how round-robin distribution affects the effective per-key rate at the API. +6. **Gaps or risks** — anything the API charges for that we don't meter, rate limit dimensions we chose not to enforce, or pricing that may be inaccurate due to variable model/tier costs. + +### Format + +Present this as a structured summary with clear headings. Example: + +``` +### Pricing +- **API charges**: $X per 1M tokens (input), $Y per 1M tokens (output) — varies by model +- **Response reports cost?**: No — only token counts in `usage` field +- **Our getCost**: Estimates cost at $Z per 1M total tokens based on median model pricing +- **Risk**: Actual cost varies by model; our estimate may over/undercharge for cheap/expensive models + +### Throttling +- **API limits**: 300 RPM per key (paid tier), 60 RPM (free tier) +- **Per-key or per-account**: Per key — more keys = more throughput +- **Our config**: 60 RPM per workspace (per_request mode) +- **With N keys**: Effective per-key rate is (total RPM across workspaces) / N +- **Headroom**: Comfortable — even 10 active workspaces at full rate = 600 RPM / 3 keys = 200 RPM per key, under the 300 RPM API limit +``` + +This summary helps reviewers verify that the pricing and rate limiting are well-calibrated and surfaces any risks that need monitoring. + +## Checklist + +- [ ] Provider added to `BYOKProviderId` in `tools/types.ts` +- [ ] Provider added to `VALID_PROVIDERS` in the BYOK keys API route +- [ ] API pricing docs researched — understand per-unit cost and whether the API reports cost in responses +- [ ] API rate limits researched — understand RPM/TPM limits, per-key vs per-account, and plan tiers +- [ ] `hosting` config added to the tool with `envKeyPrefix`, `apiKeyParam`, `byokProviderId`, `pricing`, and `rateLimit` +- [ ] `getCost` throws if required cost data is missing from the response +- [ ] Cost data captured in `transformResponse` or `postProcess` if API provides it +- [ ] `hideWhenHosted: true` added to the API key subblock in the block config +- [ ] Provider entry added to the BYOK settings UI with icon and description +- [ ] Env vars documented: `{PREFIX}_COUNT` and `{PREFIX}_1..N` +- [ ] Pricing and throttling summary provided to reviewer diff --git a/.claude/commands/council.md b/.claude/commands/council.md new file mode 100644 index 00000000000..9bbd9bfbedf --- /dev/null +++ b/.claude/commands/council.md @@ -0,0 +1,12 @@ +--- +description: Spawn task agents to explore a given area of interest in the codebase +argument-hint: +--- + +Based on the given area of interest, please: + +1. Dig around the codebase in terms of that given area of interest, gather general information such as keywords and architecture overview. +2. Spawn off n=10 (unless specified otherwise) task agents to dig deeper into the codebase in terms of that given area of interest, some of them should be out of the box for variance. +3. Once the task agents are done, use the information to do what the user wants. + +If user is in plan mode, use the information to create the plan. diff --git a/.claude/commands/you-might-not-need-an-effect.md b/.claude/commands/you-might-not-need-an-effect.md new file mode 100644 index 00000000000..1e798c804e9 --- /dev/null +++ b/.claude/commands/you-might-not-need-an-effect.md @@ -0,0 +1,17 @@ +--- +description: Analyze and fix useEffect anti-patterns in your code +argument-hint: [scope] [fix=true|false] +--- + +# You Might Not Need an Effect + +Arguments: +- scope: what to analyze (default: your current changes). Examples: "diff to main", "PR #123", "src/components/", "whole codebase" +- fix: whether to apply fixes (default: true). Set to false to only propose changes. + +User arguments: $ARGUMENTS + +Steps: +1. Read https://react.dev/learn/you-might-not-need-an-effect to understand the guidelines +2. Analyze the specified scope for useEffect anti-patterns +3. If fix=true, apply the fixes. If fix=false, propose the fixes without applying. diff --git a/.claude/rules/landing-seo-geo.md b/.claude/rules/landing-seo-geo.md new file mode 100644 index 00000000000..15f9fd843b2 --- /dev/null +++ b/.claude/rules/landing-seo-geo.md @@ -0,0 +1,26 @@ +--- +paths: + - "apps/sim/app/(home)/**/*.tsx" +--- + +# Landing Page — SEO / GEO + +## SEO + +- One `

` per page, in Hero only — never add another. +- Strict heading hierarchy: H1 (Hero) → H2 (section titles) → H3 (feature names). +- Every section: `
`. +- Decorative/animated elements: `aria-hidden="true"`. +- All internal routes use Next.js `` (crawlable). External links get `rel="noopener noreferrer"`. +- Navbar is a Server Component (no `'use client'`) for immediate crawlability. Logo `` has `priority` (LCP element). +- Navbar `