@elevasis/sdk 0.5.12 → 0.5.14

package/reference/concepts.mdx

@@ -0,0 +1,164 @@
+---
+title: Concepts Reference
+description: Plain-English explanations of Elevasis SDK concepts -- glossary, workflow analogies, Zod schemas, execution model, platform tools, common errors, and design decisions
+loadWhen: "User asks what is or needs conceptual grounding"
+---
+
+This page covers core Elevasis concepts in plain English. It is the teaching vocabulary for the agent when helping you build workflows, and a reference you can return to whenever a term or behavior is unclear.
+
+## Glossary
+
+| Term          | Definition                                                                                                                                                                                         |
+| ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Workflow      | A series of named steps that run one after another. Each step does one job. The workflow receives input data and produces output data.                                                             |
+| Agent         | An autonomous AI resource with access to platform tools. Agents can make decisions and call tools on their own. Run agents with `--async` to avoid HTTP timeout limits on long-running executions. |
+| Resource      | Anything you deploy to the platform -- a workflow or an agent. Each resource has a unique ID.                                                                                                      |
+| Step          | One job inside a workflow. A step receives data, processes it, and passes data to the next step.                                                                                                   |
+| Schema        | A description of what your data looks like. Schemas validate that input and output data has the right shape -- the right fields with the right types.                                              |
+| Credential    | A saved API key or login for an external service (Gmail, Attio, Stripe). Stored securely on the platform, never in your code.                                                                      |
+| Execution     | One run of a resource. Each time someone triggers your workflow, that is one execution.                                                                                                            |
+| Deployment    | The act of uploading your code to the platform. After deploying, your resources are live and can be executed.                                                                                      |
+| Platform Tool | A pre-built integration the platform provides. You call platform tools from your workflow steps using `platform.call()`.                                                                           |
+| Organization  | Your team or company on the Elevasis platform. Resources, credentials, and executions belong to an organization.                                                                                   |
+| Handler       | The function inside a step that does the actual work. It receives input data and returns output data.                                                                                              |
+| Entry Point   | The first step that runs when a workflow is executed. Every workflow must have one.                                                                                                                |
+| Resource ID   | A unique lowercase name for your resource (e.g., `lead-scorer`, `send-welcome-email`). Must be unique within your organization.                                                                    |
+| Workspace     | Your Elevasis project directory. Contains resources (workflows and agents), documentation, and optionally a database connection and custom apps. Created by `elevasis-sdk init`.                   |
+| Data Table    | A table in your database (e.g., Supabase) that stores structured data your workflows can read and write. Defined in `data/schema.ts` as documentation for the agent.                               |
+
+---
+
+## What is a Workflow?
+
+A workflow is a piece of automation that runs on the Elevasis platform. You define the steps in TypeScript; the platform handles running them, logging results, and retrying on failure.
+
+### Two Analogies
+
+**Recipe analogy:** A recipe has ingredients (input), instructions (steps), and a finished dish (output). Each instruction is one step. You follow them in order. If a step fails (you burn the sauce), the recipe stops.
+
+**Assembly line analogy:** Raw material goes in one end (input). Each station does one job (step). The finished product comes out the other end (output).
+
+### When to Use a Workflow
+
+- Automating a repeatable task with defined input and output
+- Chaining multiple actions together (fetch data, process it, send an email)
+- When you need the platform to handle execution, retries, and logging
+
+### When NOT to Use a Workflow
+
+- One-off tasks you will only do once
+- Tasks that need constant human judgment at every step
+
+---
+
+## Understanding Schemas (Zod)
+
+### What Schemas Do
+
+Schemas describe and validate the shape of data your workflow expects and produces. If someone sends the wrong data, the platform rejects it before your code runs. This prevents confusing errors deep inside your handler.
+
+The Elevasis SDK uses [Zod](https://zod.dev) for schema definition. Zod is a TypeScript-first validation library. Every workflow has an `inputSchema` and an `outputSchema`.
+
+### Common Zod Types
+
+| Zod Type                         | What It Means                   | Example                       |
+| -------------------------------- | ------------------------------- | ----------------------------- |
+| `z.string()`                     | Text                            | `"hello"`, `"user@email.com"` |
+| `z.number()`                     | A number                        | `42`, `3.14`                  |
+| `z.boolean()`                    | True or false                   | `true`, `false`               |
+| `z.array(z.string())`            | A list of text values           | `["a", "b", "c"]`             |
+| `z.object({ name: z.string() })` | A group of named fields         | `{ "name": "Jane" }`          |
+| `z.string().optional()`          | Text that might be missing      | `"hello"` or not provided     |
+| `z.enum(['a', 'b', 'c'])`        | One of a specific set of values | `"a"`                         |
+| `z.string().email()`             | Text that must be a valid email | `"user@example.com"`          |
+
+### Why `z.infer` Exists
+
+`z.infer` creates a TypeScript type from a schema so the type system can check your code. You define the schema once and get both runtime validation and compile-time checking. Without it, you would have to define the same shape twice -- once as a Zod schema and once as a TypeScript type.
+
+```ts
+const myInput = z.object({ name: z.string(), age: z.number() });
+type MyInput = z.infer<typeof myInput>;
+// MyInput is now: { name: string; age: number }
+```
+
+### Common Schema Mistakes
+
+- Forgetting `.optional()` on fields that might be missing -- the platform will reject valid input that omits those fields
+- Returning data from a handler that does not match the output schema -- causes `outputSchema validation failed`
+- Misspelling field names -- the schema says `companyName`, but the handler returns `company_name`
+
+---
+
+## The Execution Model
+
+### What Happens When You Run a Workflow
+
+1. A request arrives at the Elevasis platform (someone runs `elevasis-sdk exec` or a schedule triggers)
+2. The platform creates a temporary server just for this execution
+3. Your code runs on that server
+4. The result is sent back
+5. The temporary server is deleted
+
+### Practical Implications
+
+| What You Might Expect       | What Actually Happens                 | Why                           |
+| --------------------------- | ------------------------------------- | ----------------------------- |
+| Files I create persist      | Files disappear after execution       | The server is temporary       |
+| I can see logs in real-time | Logs appear after execution completes | No streaming from workers     |
+| My code runs on my computer | Your code runs on Elevasis servers    | That is what "deploy" means   |
+| I can use unlimited memory  | 256MB memory limit per execution      | Prevents runaway processes    |
+| Executions share state      | Each execution is independent         | No shared memory between runs |
+| I can call external APIs    | Yes, outbound network is unrestricted | Workers have internet access  |
+
+### What "completed" vs "failed" Means
+
+- **completed** -- Your code ran successfully and returned output
+- **failed** -- Something went wrong: your code threw an error, timed out (300s default), or ran out of memory
+
+---
+
+## Platform Tools Overview
+
+Platform tools are pre-built integrations the platform provides. You call them from inside workflow steps using `platform.call()` or typed adapters without managing API keys in your code. The platform supports 70+ tools across 12 categories including CRM, email, payments, AI, storage, and more. Credentials are stored securely on the platform and injected at runtime -- they never appear in your code.
+
+See [Platform Tools](platform-tools/index.mdx) for the complete catalog, credential setup, and code examples.
+
+---
+
+## Common Errors (Quick Reference)
+
+| Error                                     | How to Fix                                                                      |
+| ----------------------------------------- | ------------------------------------------------------------------------------- |
+| `ELEVASIS_PLATFORM_KEY not set`           | Add `ELEVASIS_PLATFORM_KEY=sk_...` to `.env`                                    |
+| `Schema validation failed`                | Compare error field names to your schema. Check types and required vs optional. |
+| `Cannot find module '@elevasis/sdk'`      | Run `pnpm install`                                                              |
+| `PlatformToolError: credential not found` | Check spelling and case in the command center UI                                |
+| `Execution timeout (300s)`                | Optimize handler or break into smaller steps                                    |
+| `Cannot find name 'z'`                    | Add `import { z } from 'zod'`                                                   |
+| `outputSchema validation failed`          | Check field names, types, and required fields against output schema             |
+| `NODE_ENV=development` in .env            | Remove `NODE_ENV` from `.env`                                                   |
+
+For the full error catalog with detailed diagnostic steps, see [Troubleshooting](troubleshooting.mdx).
+
+---
+
+## Design Decisions Guide
+
+### Single-Step vs Multi-Step
+
+Use a single step when the workflow does one thing -- validate an email, format a message, call one API.
+
+Use multiple steps when you have distinct phases (fetch data, process it, send a notification) or when you want separate error handling per phase. Each step failure is logged independently, making it easier to identify where something went wrong.
+
+### When to Use Conditional Routing
+
+Use `StepType.CONDITIONAL` when different inputs should follow different processing paths.
+
+Example: score >= 80 goes to the approve path, score >= 50 goes to the review path, everything else goes to the reject path. Each path can have its own steps and logic.
+
+Always include a `default` fallback step for inputs that do not match any condition. Without a fallback, an unmatched execution will fail.
+
+---
+
+**Last Updated:** 2026-02-26