@elevasis/sdk 0.4.6 → 0.4.7

package/reference/templates/text-classifier.mdx

@@ -0,0 +1,147 @@
+---
+title: "Template: Text Classifier"
+description: "Multi-label text classification with structured output -- classify text into predefined categories using an LLM with JSON output"
+loadWhen: "Applying the text-classifier workflow template"
+---
+
+**Category:** AI
+
+**Platform Tools:** `llm` (structured generation)
+
+**Credentials Required:**
+
+- LLM API keys are resolved server-side from platform configuration (no credential name needed)
+
+---
+
+## What This Workflow Does
+
+Classifies input text into one or more predefined categories using an LLM. Returns structured output with category assignments and confidence reasoning. Suitable for ticket categorization, email routing, content tagging, sentiment analysis, and any text classification task where the categories are known in advance.
+
+---
+
+## Input Schema
+
+```typescript
+z.object({
+  text: z.string(),                        // Text to classify
+  categories: z.array(z.string()),         // Available category labels
+  multiLabel: z.boolean().optional(),      // Allow multiple categories (default: false)
+  instructions: z.string().optional(),     // Additional instructions for the LLM
+})
+```
+
+## Output Schema
+
+```typescript
+z.object({
+  categories: z.array(z.string()),         // Assigned category labels
+  reasoning: z.string(),                   // LLM explanation of classification
+  confidence: z.enum(['high', 'medium', 'low']),
+})
+```
+
+---
+
+## Workflow Code Pattern
+
+```typescript
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { platform } from '@elevasis/sdk/worker'
+import { z } from 'zod'
+
+const inputSchema = z.object({
+  text: z.string(),
+  categories: z.array(z.string()),
+  multiLabel: z.boolean().optional(),
+  instructions: z.string().optional(),
+})
+const outputSchema = z.object({
+  categories: z.array(z.string()),
+  reasoning: z.string(),
+  confidence: z.enum(['high', 'medium', 'low']),
+})
+
+type Input = z.infer<typeof inputSchema>
+
+export const textClassifier: WorkflowDefinition = {
+  config: {
+    resourceId: 'text-classifier',
+    name: 'Text Classifier',
+    type: 'workflow',
+    description: 'Classifies text into predefined categories using an LLM',
+    version: '1.0.0',
+    status: 'dev',
+  },
+  contract: { inputSchema, outputSchema },
+  steps: {
+    classify: {
+      id: 'classify',
+      name: 'Classify Text',
+      description: 'Use LLM to classify the input text',
+      inputSchema,
+      outputSchema,
+      handler: async (input) => {
+        const { text, categories, multiLabel, instructions } = input as Input
+        const mode = multiLabel ? 'one or more' : 'exactly one'
+        const categoryList = categories.map(c => `- ${c}`).join('\n')
+
+        const prompt = `Classify the following text into ${mode} of these categories:
+${categoryList}
+${instructions ? `\nAdditional instructions: ${instructions}` : ''}
+
+Text to classify:
+"${text}"
+
+Return JSON with:
+- categories: array of matching category names (from the list above only)
+- reasoning: brief explanation of your classification
+- confidence: "high" (very clear match), "medium" (reasonable but uncertain), or "low" (ambiguous)`
+
+        const result = await platform.call({
+          tool: 'llm',
+          method: 'generate',
+          params: {
+            provider: 'openai',
+            model: 'gpt-4o-mini',
+            messages: [{ role: 'user', content: prompt }],
+            responseSchema: {
+              type: 'object',
+              properties: {
+                categories: { type: 'array', items: { type: 'string' } },
+                reasoning: { type: 'string' },
+                confidence: { type: 'string', enum: ['high', 'medium', 'low'] },
+              },
+            },
+          },
+        }) as { categories: string[]; reasoning: string; confidence: 'high' | 'medium' | 'low' }
+
+        // Validate that returned categories are from the allowed list
+        const validCategories = result.categories.filter(c => categories.includes(c))
+
+        return {
+          categories: validCategories,
+          reasoning: result.reasoning,
+          confidence: result.confidence,
+        }
+      },
+      next: null,
+    },
+  },
+  entryPoint: 'classify',
+}
+```
+
+---
+
+## Adaptation Notes
+
+- **Category design:** Help the user define clear, mutually exclusive category names. Ambiguous categories produce inconsistent results.
+- **Multi-label use:** Enable `multiLabel: true` when a single piece of text can legitimately belong to multiple categories (e.g., a support ticket about "billing AND account access").
+- **Confidence routing:** Common pattern: use the output with `StepType.CONDITIONAL` routing. High confidence routes to automated processing; low confidence routes to human review.
+- **Model selection:** `gpt-4o-mini` is fast and cost-effective for classification. For complex or nuanced categorization, suggest `gpt-4o`.
+- **Skill adaptation:** For beginners, explain what "structured output" means and why the LLM returns JSON instead of free text.
+
+---
+
+**Last Updated:** 2026-02-26

package/reference/templates/web-scraper.mdx

@@ -0,0 +1,135 @@
+---
+title: "Template: Web Scraper"
+description: "Apify-based web scraper that stores results in Supabase -- fetch structured data from any website via Apify actors"
+loadWhen: "Applying the web-scraper workflow template"
+---
+
+**Category:** Data Collection
+
+**Platform Tools:** `apify` (run actor), `supabase` (insert results)
+
+**Credentials Required:**
+
+- `apify` -- Apify API token (bearer type)
+- `my-database` -- Supabase project URL and service role key
+
+---
+
+## What This Workflow Does
+
+Runs an Apify actor to scrape structured data from a URL, then stores the scraped results in a Supabase table. The actor and table names are configurable. Suitable for extracting product listings, job postings, contact information, or any structured web content.
+
+---
+
+## Input Schema
+
+```typescript
+z.object({
+  actorId: z.string(),          // Apify actor ID (e.g., 'apify/web-scraper')
+  startUrls: z.array(z.string()), // URLs to scrape
+  tableName: z.string(),        // Supabase table to store results in
+  maxItems: z.number().optional(), // Maximum number of items to collect (default: 100)
+})
+```
+
+## Output Schema
+
+```typescript
+z.object({
+  itemsScraped: z.number(),     // Total items scraped
+  itemsInserted: z.number(),    // Items successfully inserted into Supabase
+  runId: z.string(),            // Apify run ID for reference
+})
+```
+
+---
+
+## Workflow Code Pattern
+
+```typescript
+import type { WorkflowDefinition } from '@elevasis/sdk'
+import { StepType } from '@elevasis/sdk'
+import { platform, PlatformToolError } from '@elevasis/sdk/worker'
+import { z } from 'zod'
+
+const inputSchema = z.object({
+  actorId: z.string(),
+  startUrls: z.array(z.string()),
+  tableName: z.string(),
+  maxItems: z.number().optional(),
+})
+const outputSchema = z.object({
+  itemsScraped: z.number(),
+  itemsInserted: z.number(),
+  runId: z.string(),
+})
+
+type Input = z.infer<typeof inputSchema>
+
+export const webScraper: WorkflowDefinition = {
+  config: {
+    resourceId: 'web-scraper',
+    name: 'Web Scraper',
+    type: 'workflow',
+    description: 'Scrapes structured data via Apify and stores in Supabase',
+    version: '1.0.0',
+    status: 'dev',
+  },
+  contract: { inputSchema, outputSchema },
+  steps: {
+    scrape: {
+      id: 'scrape',
+      name: 'Run Apify Actor',
+      description: 'Execute the Apify actor and collect results',
+      inputSchema,
+      outputSchema: z.object({ items: z.array(z.unknown()), runId: z.string() }),
+      handler: async (input) => {
+        const { actorId, startUrls, maxItems } = input as Input
+        const result = await platform.call({
+          tool: 'apify',
+          method: 'runActor',
+          credential: 'apify',
+          params: { actorId, input: { startUrls: startUrls.map(url => ({ url })), maxItems: maxItems ?? 100 } },
+        }) as { items: unknown[]; runId: string }
+        return { items: result.items, runId: result.runId }
+      },
+      next: { type: StepType.LINEAR, target: 'store' },
+    },
+    store: {
+      id: 'store',
+      name: 'Store Results',
+      description: 'Insert scraped items into Supabase',
+      inputSchema: z.object({ items: z.array(z.unknown()), runId: z.string(), tableName: z.string() }),
+      outputSchema,
+      handler: async (input, context) => {
+        const { items, runId, tableName } = input as { items: unknown[]; runId: string; tableName: string }
+        const data = items.map(item => ({ ...(item as Record<string, unknown>), scraped_at: new Date().toISOString() }))
+        await platform.call({
+          tool: 'supabase',
+          method: 'insert',
+          credential: 'my-database',
+          params: { table: tableName, data },
+        })
+        context.logger.info('Stored scraped items', { count: data.length, table: tableName })
+        return { itemsScraped: items.length, itemsInserted: data.length, runId }
+      },
+      next: null,
+    },
+  },
+  entryPoint: 'scrape',
+}
+```
+
+---
+
+## Adaptation Notes
+
+- **Credential names:** Replace `'apify'` and `'my-database'` with the credential names the user configured in the command center.
+- **Table schema:** Ensure the Supabase table exists and has columns that match the scraped data fields. The agent should check `data/schema.ts` if it exists.
+- **Actor selection:** Apify has hundreds of public actors. Common choices: `apify/web-scraper` (generic), `apify/cheerio-scraper` (fast HTML parsing), specialized actors for LinkedIn, Amazon, etc.
+- **Error handling:** Add try/catch for `PlatformToolError` if partial failure tolerance is needed.
+- **Skill adaptation:** For beginners, explain what Apify is and walk through actor selection before generating code.
+
+---
+
+**Last Updated:** 2026-02-26

package/reference/troubleshooting/common-errors.mdx

@@ -0,0 +1,210 @@
+---
+title: "Common Errors"
+description: "Static SDK-level error catalog -- CLI errors, deployment errors, schema validation, platform tool failures, and runtime errors with diagnostic steps"
+loadWhen: "Debugging an unknown error not found in workspace memory"
+---
+
+This is the static SDK-level error catalog. Check `.claude/memory/errors/` first for workspace-specific fixes. Use this file when the error is new to the workspace or when the memory has no match.
+
+---
+
+## CLI Errors
+
+### ELEVASIS_API_KEY not set
+
+**Cause:** The `.env` file is missing the API key, or the file was not loaded.
+
+**Fix:**
+1. Check that `.env` exists in the workspace root
+2. Confirm it contains `ELEVASIS_API_KEY=sk_...`
+3. Make sure you are running the CLI from the workspace directory (where `.env` is located)
+4. If the file exists with the right content, run `elevasis check` again
+
+### Cannot connect to API
+
+**Cause:** Network issue or the API URL is incorrect.
+
+**Fix:**
+1. Check your internet connection
+2. If using a custom API URL via `--api-url` or `ELEVASIS_API_URL`, verify it is correct
+3. Remove `NODE_ENV=development` from `.env` if you are not running a local API server
+
+### NODE_ENV=development in .env
+
+**Cause:** The SDK is pointing at a local API server (port 5170 by default) instead of the hosted platform.
+
+**Fix:** Remove `NODE_ENV=development` from `.env`. The CLI connects to the hosted platform by default.
+
+---
+
+## Validation Errors (elevasis check)
+
+### Duplicate resource ID
+
+**Message:** `Duplicate resource ID 'name' in organization 'org'`
+
+**Cause:** Two resources in `src/` share the same `resourceId`.
+
+**Fix:** Each resource must have a unique `resourceId` within your organization. Check all files in `src/workflows/` and rename the duplicate.
+
+### Workflow step references non-existent next step
+
+**Message:** `Workflow step 'stepA' references non-existent next step 'stepB'`
+
+**Cause:** A step's `next.target` or `next.routes[*].target` points to a step name that does not exist in the `steps` record.
+
+**Fix:** Check the spelling of the target step name. All target values must exactly match keys in the `steps` object.
+
+### Missing entryPoint
+
+**Cause:** The workflow's `entryPoint` field names a step that does not exist in `steps`.
+
+**Fix:** Confirm `entryPoint` matches an exact key in your `steps` record.
+
+---
+
+## Schema Validation Errors
+
+### Schema validation failed (input)
+
+**Message:** `Schema validation failed` with field-level details
+
+**Cause:** The input passed to the workflow does not match the `inputSchema`.
+
+**Fix:**
+1. Read the error's field details -- it names the failing field and expected type
+2. Compare against your `inputSchema` definition
+3. Common causes: wrong type (string vs number), missing required field, extra field not in schema, misspelled field name
+4. Check that `z.infer` types match what your handler actually receives
+
+### outputSchema validation failed
+
+**Cause:** Your handler's return value does not match the workflow's `outputSchema`.
+
+**Fix:**
+1. Compare what your handler returns to what `outputSchema` expects
+2. Check field names for typos (the schema says `companyName`, handler returns `company_name`)
+3. Check types -- the schema says `z.number()` but the handler returns a string
+4. Check required vs optional -- do not return undefined for a required field
+
+### Cannot find name 'z'
+
+**Cause:** Missing Zod import.
+
+**Fix:** Add `import { z } from 'zod'` at the top of the file.
+
+---
+
+## TypeScript Errors
+
+### Type 'X' is not assignable to type 'Y'
+
+**Cause:** The data flowing into a step or returned from a handler does not match the declared type.
+
+**Fix:**
+1. Check the input type annotation on the handler: `async (input: MyInput) => ...`
+2. Confirm the `z.infer<typeof mySchema>` type matches what the previous step returns
+3. Check that all optional fields are handled (do not assume they are always present)
+
+### Cannot find module '@elevasis/sdk'
+
+**Cause:** Dependencies are not installed.
+
+**Fix:** Run `pnpm install` in the workspace root.
+
+### Cannot find module '@elevasis/sdk/worker'
+
+**Cause:** Dependencies not installed, or using an old SDK version that does not export the `worker` subpath.
+
+**Fix:**
+1. Run `pnpm install`
+2. Check that `@elevasis/sdk` version is recent enough to include `worker` export
+3. Confirm your `tsconfig.json` has `"moduleResolution": "Bundler"` or `"NodeNext"`
+
+---
+
+## Platform Tool Errors
+
+### PlatformToolError: credential not found
+
+**Cause:** The credential name passed to `platform.call()` does not match any credential stored in the platform.
+
+**Fix:**
+1. Check spelling and case -- credential names are case-sensitive
+2. Open the command center and confirm the credential exists and is named exactly as referenced
+3. Check that the credential belongs to the correct organization
+
+### PlatformToolError: credentials_invalid
+
+**Cause:** The credential exists but has the wrong shape for the tool being called.
+
+**Fix:**
+1. For the `http` tool: verify the credential type matches the API's auth method (bearer, api-key-header, basic, etc.)
+2. For the Supabase tool: verify the credential contains `url` and `serviceRoleKey` fields
+3. Re-create the credential in the command center if the format is wrong
+
+### PlatformToolError: timeout_error
+
+**Cause:** The platform tool call took longer than 60 seconds.
+
+**Fix:**
+1. Check if the external API is slow or down
+2. Reduce the amount of data being processed in a single call
+3. For `http` tool: the external endpoint may be unresponsive -- check directly
+
+### PlatformToolError: service_unavailable
+
+**Cause:** The platform service or integration adapter is not available.
+
+**Fix:**
+1. Check the Elevasis status page
+2. Retry -- transient availability issues resolve quickly
+
+---
+
+## Runtime Errors
+
+### Execution timeout (300s)
+
+**Cause:** The entire workflow execution exceeded the 300-second limit.
+
+**Fix:**
+1. Identify which step is slow -- check execution logs for step timing
+2. Reduce work per step or parallelize if possible
+3. For long-running operations, consider breaking into multiple workflows with the `execution` platform tool to chain them
+
+### Worker ran out of memory (256MB limit)
+
+**Cause:** The workflow processed too much data in memory at once.
+
+**Fix:**
+1. Reduce the size of data loaded per execution
+2. Use pagination for large data sets (fetch in chunks, process one at a time)
+3. Avoid loading large files or arrays entirely into memory
+
+### Module resolution error at runtime
+
+**Cause:** An import in your workflow bundle cannot be resolved.
+
+**Fix:**
+1. Run `elevasis check` -- it catches most resolution errors before deploy
+2. If the import is a built-in Node.js module, ensure it is compatible with the worker environment
+3. Avoid imports that require file system access or native modules
+
+---
+
+## Memory Error Structure
+
+When recording a new error in `.claude/memory/errors/`, use this table format:
+
+```
+| Error | Context | Fix | Count | Last Seen | Status |
+| --- | --- | --- | --- | --- | --- |
+| `Schema validation failed` on lead-scorer | Added score field | Changed score from z.string() to z.number() | 1 | 2026-02-26 | Resolved |
+```
+
+Status values: `Resolved` (fixed this session), `Recurring` (seen 2+ times), `Promoted` (3+ times, now in Rules).
+
+---
+
+**Last Updated:** 2026-02-26

package/reference/getting-started/project-structure.mdx

@@ -1,148 +0,0 @@
----
-title: Project Structure
-description: Each file scaffolded by elevasis init and its purpose in the development workflow
----
-
-`elevasis init` creates a complete project structure. This page explains what each file does and when you will interact with it.
-
----
-
-## Source Files
-
-### `src/index.ts`
-
-Your resource definitions live here. This file must export an `OrganizationResources` object as its default export. The scaffolded file contains a working echo workflow that demonstrates the `z.infer` pattern for Zod schema types.
-
-Every resource you add -- workflows and agents -- is registered through this default export.
-
-### `elevasis.config.ts`
-
-Project-level configuration. The scaffolded file contains commented-out options (`defaultStatus`, `dev.port`) so you can discover available settings without having to look them up. Leave this file minimal; the platform provides sensible defaults.
-
----
-
-## Documentation
-
-### `docs/index.mdx`
-
-The entry point for your project's documentation. Documentation files in `docs/` are deployed alongside your code during `elevasis deploy` and rendered in the Elevasis platform UI.
-
-Use MDX frontmatter to set page metadata:
-
-```yaml
----
-title: Overview
-description: Documentation for this project
-order: 0
----
-```
-
-Add more pages by creating additional `.mdx` files in `docs/`. Nested directories create sections: `docs/guides/setup.mdx` becomes a `guides/setup` page under your deployment's documentation.
-
----
-
-## Configuration Files
-
-### `.env`
-
-Contains your `ELEVASIS_API_KEY`. This file is gitignored. Never commit it.
-
-### `.env.example`
-
-A git-safe template showing which variables are needed:
-
-```
-ELEVASIS_API_KEY=sk_your_key_here
-```
-
-Commit this file so collaborators know what to configure.
-
-### `.npmrc`
-
-Sets `auto-install-peers = true`. The SDK uses Zod as a peer dependency, so this ensures Zod installs automatically.
-
-### `tsconfig.json`
-
-App-focused TypeScript configuration. It does not include `declaration` or `declarationMap` settings because your project is a deployable application, not a library.
-
-### `.gitignore`
-
-Pre-configured to exclude:
-- `.env` -- API key
-- `__elevasis_worker.ts` -- temporary file generated during deployment
-- `.claude/settings.local.json` -- local Claude Code overrides
-- `.claude/profile.json` -- your personal onboarding profile
-
----
-
-## Claude Code Integration
-
-The `.claude/` directory and `CLAUDE.md` give Claude Code full awareness of the SDK, CLI, and your project structure from the first session.
-
-### `CLAUDE.md`
-
-The most important file for AI-assisted development. It provides Claude Code with:
-
-- **Project orientation** -- what an Elevasis SDK project is and how it works
-- **Project structure** -- which files contain resources, documentation, and configuration
-- **SDK patterns** -- working code examples for resource definitions, Zod schemas, and the `OrganizationResources` export
-- **CLI reference** -- all commands with flags (`check`, `deploy`, `exec`, `resources`, `executions`, `execution`, `deployments`, `env list/set/remove`)
-- **Development rules** -- conventions the agent should enforce (source in `src/`, docs in `docs/`, use `@elevasis/sdk` types only)
-
-Do not remove or heavily edit `CLAUDE.md`. It is the primary context source that makes the slash commands work well.
-
-### `.claude/settings.json`
-
-Sets `autoCompact: false`. This prevents Claude Code from automatically compacting context during long sessions, which can lose important earlier context about your project.
-
-### `.claude/profile.json`
-
-Created automatically on your first Claude Code session. The agent runs a one-time onboarding flow asking about your organization, project goals, and experience level. Answers are stored here and used to personalize subsequent sessions.
-
-This file is gitignored -- it is personal to you and not shared with collaborators.
-
----
-
-## Slash Commands
-
-The `.claude/commands/` directory contains three commands covering the core development loop. Invoke them in Claude Code with `/docs`, `/resource`, and `/deploy`.
-
-### `/docs` -- Documentation Assistant
-
-Helps you write and maintain documentation in `docs/`. Three operations:
-
-- **No arguments** -- Review existing `docs/` files, identify undocumented resources and gaps, suggest improvements
-- **`create <page-name>`** -- Scaffold a new documentation page with correct frontmatter, populated from your resource definitions
-- **`review`** -- Check all `docs/` files for accuracy against the actual code in `src/`, flag mismatches between documented schemas and implementation
-
-### `/resource` -- Resource Scaffolding
-
-Scaffolds new workflow definitions with proper types, Zod schemas, and step structure. Three operations:
-
-- **`workflow <name>`** -- Single-step workflow with Zod input/output schemas, config object, contract, step handler, and addition to the `OrganizationResources` export
-- **`multi-step <name>`** -- Multi-step workflow with `StepType.LINEAR` or `StepType.CONDITIONAL`, connected steps, and per-step schemas
-- **`tool-step <name>`** -- Step that calls a platform tool via `platform.call()` with `PlatformToolError` error handling and a credential note
-
-### `/deploy` -- Deployment Assistant
-
-Guides you through validation and deployment. Two operations:
-
-- **No arguments** -- Runs `elevasis check`, reports any validation errors, then runs `elevasis deploy` if check passes. Analyzes failure output and suggests fixes if the deploy fails
-- **`status`** -- Runs `elevasis deployments` and `elevasis resources` to show current deployment state
-
----
-
-## File Reference
-
-| File | When You Edit It |
-|------|-----------------|
-| `src/index.ts` | Adding or modifying resources |
-| `docs/index.mdx` | Updating project documentation |
-| `elevasis.config.ts` | Changing project-level settings |
-| `.env` | Adding environment variables |
-| `CLAUDE.md` | Rarely -- only to add project-specific context |
-| `.claude/commands/*.md` | Rarely -- commands work well as scaffolded |
-
----
-
-**Last Updated:** 2026-02-25