automations

type Action ¶

type Action struct {
	Name        string
	DisplayName string
	Description string
	Props       []PropSpec
	Run         func(ctx context.Context, rc RunContext) (any, error)
}

Action is one invocable capability of a connector. Props declares its inputs (drives the catalogue + the MCP tool input schema). Run is the side-effecting body; it MUST handle every error explicitly and MUST NOT leak another org's data.

type AddActionRequest ¶

type AddActionRequest struct {
	ParentStep string      `json:"parentStep"`
	Action     *FlowAction `json:"action"`
}

AddActionRequest inserts Action after the step named ParentStep (empty ⇒ append to the end of the chain, or set as the trigger's first action).

type Catalog ¶

type Catalog struct {
	ConnectorCount int                 `json:"connectorCount"`
	Connectors     []ConnectorMetadata `json:"connectors"`
}

Catalog is the browse catalogue served at GET /v1/automations/connectors. It is the go:embed'd catalog/catalog.json, seeded with the Tier-A connectors and later overwritten with the full 700+ connector set at this EXACT schema.

type ChangeNameRequest ¶

type ChangeNameRequest struct {
	DisplayName string `json:"displayName"`
}

ChangeNameRequest renames the version.

type ChangeStatusRequest ¶

type ChangeStatusRequest struct {
	Status FlowStatus `json:"status"`
}

ChangeStatusRequest flips ENABLED/DISABLED.

type Connector ¶

type Connector struct {
	Name        string
	DisplayName string
	AuthType    string // "none" | "bot_token" | "oauth2" — for the catalogue card
	AuthReq     bool
	Actions     map[string]*Action
	Triggers    map[string]*Trigger
}

Connector is one connectable capability provider. Name == the integrations provider id where credentials apply.

type ConnectorAction ¶

type ConnectorAction struct {
	Name        string     `json:"name"`
	DisplayName string     `json:"displayName"`
	Description string     `json:"description"`
	Props       []PropSpec `json:"props"`
}

ConnectorAction / ConnectorTrigger are the catalogue's action/trigger descriptors.

type ConnectorAuth ¶

type ConnectorAuth struct {
	Type     string `json:"type"`
	Required bool   `json:"required"`
}

ConnectorAuth is the catalogue's auth descriptor: which credential a connector needs ("none" for core, "oauth2"/"bot_token" for a connected provider) and whether it is required.

type ConnectorMetadata ¶

type ConnectorMetadata struct {
	Name        string             `json:"name"`
	DisplayName string             `json:"displayName"`
	Description string             `json:"description"`
	LogoURL     string             `json:"logoUrl"`
	Version     string             `json:"version"`
	Categories  []string           `json:"categories"`
	Auth        ConnectorAuth      `json:"auth"`
	Actions     []ConnectorAction  `json:"actions"`
	Triggers    []ConnectorTrigger `json:"triggers"`
}

ConnectorMetadata is one catalogue entry. The catalog WIRE schema models a connector's actions/triggers as arrays, so this Go shape uses arrays to match the wire exactly, as the contract requires.

type ConnectorTrigger ¶

type ConnectorTrigger struct {
	Name        string     `json:"name"`
	DisplayName string     `json:"displayName"`
	Description string     `json:"description"`
	Strategy    string     `json:"strategy"`
	Props       []PropSpec `json:"props"`
}

type DeleteActionRequest ¶

type DeleteActionRequest struct {
	Names []string `json:"names"`
}

DeleteActionRequest removes the named steps and relinks the chain.

type Flow ¶

type Flow struct {
	ID                 string          `json:"id"`
	Org                string          `json:"projectId"` // projectId == org (server-derived)
	ExternalID         string          `json:"externalId"`
	FolderID           string          `json:"folderId"`
	Status             FlowStatus      `json:"status"`
	PublishedVersionID string          `json:"publishedVersionId"`
	Metadata           json.RawMessage `json:"metadata,omitempty"`
	Created            int64           `json:"created"`
	Updated            int64           `json:"updated"`
}

Flow is an org-scoped automation. projectId IS the org (the TS `projectId` field), always server-derived from principal.Org and NEVER trusted from a request body — a caller can never author a flow into another tenant.

type FlowAction ¶

type FlowAction struct {
	Name        string       `json:"name"`
	Type        string       `json:"type"` // PIECE | CODE | ROUTER | LOOP_ON_ITEMS
	DisplayName string       `json:"displayName"`
	Valid       bool         `json:"valid"`
	Skip        bool         `json:"skip,omitempty"`
	Settings    StepSettings `json:"settings"`
	NextAction  *FlowAction  `json:"nextAction,omitempty"`
}

FlowAction is an action node (actions/action.ts). The engine walks the linear NextAction chain; the tree discriminants (ROUTER/LOOP) are modeled for contract fidelity but branch/loop execution is out of Phase-1 scope (see operations.go).

type FlowOperation ¶

type FlowOperation struct {
	Type    FlowOperationType `json:"type"`
	Request json.RawMessage   `json:"request"`
}

FlowOperation is the discriminated-union envelope the builder POSTs to /v1/automations/flows/:id/operations: a type + an opaque request the apply switch decodes per type.

type FlowOperationType ¶

type FlowOperationType string

FlowOperationType mirrors operations/index.ts FlowOperationType — the builder's edit-op discriminants. The engine applies the linear-chain subset (see operations.go); tree-restructuring ops are honestly rejected, never faked.

const (
	OpAddAction     FlowOperationType = "ADD_ACTION"
	OpUpdateAction  FlowOperationType = "UPDATE_ACTION"
	OpDeleteAction  FlowOperationType = "DELETE_ACTION"
	OpMoveAction    FlowOperationType = "MOVE_ACTION"
	OpUpdateTrigger FlowOperationType = "UPDATE_TRIGGER"
	OpChangeName    FlowOperationType = "CHANGE_NAME"
	OpChangeStatus  FlowOperationType = "CHANGE_STATUS"
)

type FlowRun ¶

type FlowRun struct {
	ID            string        `json:"id"`
	Org           string        `json:"-"`
	FlowID        string        `json:"flowId"`
	FlowVersionID string        `json:"flowVersionId"`
	WorkflowID    string        `json:"-"`
	Status        FlowRunStatus `json:"status"`
	StartTime     int64         `json:"startTime"`
	FinishTime    int64         `json:"finishTime"`
	Created       int64         `json:"created"`
	Updated       int64         `json:"updated"`
}

FlowRun is an execution record (flow-run/flow-run.ts). WorkflowID (the tasks engine handle) equals ID and is internal — resume/describe address the engine through it, scoped to the org's namespace.

type FlowRunInput ¶

type FlowRunInput struct {
	Owner         string     `json:"owner"`
	FlowID        string     `json:"flowId"`
	FlowVersionID string     `json:"flowVersionId"`
	RunID         string     `json:"runId"`
	Steps         []FlowStep `json:"steps"`
	// Trigger is the inbound event payload that fired the flow — nil for a manual /run
	// or a bare cron tick, set by Deliver for a WEBHOOK/APP_WEBHOOK event. The workflow
	// seeds it as outputs["trigger"], so an action can reference the event that fired the
	// flow with {{trigger.field}}.
	Trigger map[string]any `json:"trigger,omitempty"`
	// Depth is the run's causation depth — how many in-platform trigger→action hops led
	// here (0 = an external origin). It rides in from TriggerEvent.Depth and lets an
	// in-platform cycle terminate at maxCausationDepth instead of amplifying.
	Depth int `json:"depth,omitempty"`
}

FlowRunInput is the durable workflow's typed input. Owner is the VALIDATED org set at flow-start from principal.Org — the SOLE credential scope and the cross-tenant isolation boundary; it is NEVER read from a request body. Steps is the flattened trigger→action chain (side-effecting steps in order).

type FlowRunResult ¶

type FlowRunResult struct {
	RunID   string         `json:"runId"`
	Status  FlowRunStatus  `json:"status"`
	Steps   int            `json:"steps"`
	Outputs map[string]any `json:"outputs"`
}

FlowRunResult is the workflow's terminal result: the final status plus every step's output, keyed by step name (the threaded outputs).

func FlowRunWorkflow(ctx workflow.Context, in FlowRunInput) (FlowRunResult, error)

type FlowRunStatus ¶

type FlowRunStatus string

FlowRunStatus mirrors execution/flow-execution.ts FlowRunStatus (the subset the engine emits; the full enum has memory/log/quota terminal states we map onto FAILED).

const (
	RunRunning   FlowRunStatus = "RUNNING"
	RunSucceeded FlowRunStatus = "SUCCEEDED"
	RunFailed    FlowRunStatus = "FAILED"
	RunPaused    FlowRunStatus = "PAUSED"
	RunQueued    FlowRunStatus = "QUEUED"
	RunCanceled  FlowRunStatus = "CANCELED"
	RunTimeout   FlowRunStatus = "TIMEOUT"
)

type FlowStatus ¶

type FlowStatus string

FlowStatus mirrors flows/flow.ts FlowStatus.

const (
	FlowEnabled  FlowStatus = "ENABLED"
	FlowDisabled FlowStatus = "DISABLED"
)

type FlowStep ¶

type FlowStep struct {
	Name       string         `json:"name"`
	PieceName  string         `json:"pieceName"`
	ActionName string         `json:"actionName"`
	Input      map[string]any `json:"input"`
}

FlowStep is one resolved, executable step in the flattened chain.

type FlowTrigger ¶

type FlowTrigger struct {
	Name        string          `json:"name"`
	Type        string          `json:"type"` // PIECE_TRIGGER | EMPTY
	DisplayName string          `json:"displayName"`
	Valid       bool            `json:"valid"`
	Strategy    TriggerStrategy `json:"strategy,omitempty"`
	Settings    StepSettings    `json:"settings"`
	NextAction  *FlowAction     `json:"nextAction,omitempty"`
}

FlowTrigger is the root of the step tree (triggers/trigger.ts). Strategy drives enable/disable (POLLING → CreateSchedule); NextAction chains into the action list.

type FlowVersion ¶

type FlowVersion struct {
	ID            string           `json:"id"`
	Org           string           `json:"-"`
	FlowID        string           `json:"flowId"`
	DisplayName   string           `json:"displayName"`
	Trigger       *FlowTrigger     `json:"trigger"`
	Valid         bool             `json:"valid"`
	State         FlowVersionState `json:"state"`
	SchemaVersion string           `json:"schemaVersion"`
	Created       int64            `json:"created"`
	Updated       int64            `json:"updated"`
}

FlowVersion is one editable revision of a flow: a display name plus the root trigger of the step tree. Org is the isolation key (never serialized).

type FlowVersionState ¶

type FlowVersionState string

FlowVersionState mirrors flows/flow-version.ts FlowVersionState.

const (
	VersionDraft  FlowVersionState = "DRAFT"
	VersionLocked FlowVersionState = "LOCKED"
)

type MoveActionRequest ¶

type MoveActionRequest struct {
	Name          string `json:"name"`
	NewParentStep string `json:"newParentStep"`
}

MoveActionRequest moves Name to sit immediately after NewParentStep.

type PropSpec ¶

type PropSpec struct {
	Name        string `json:"name"`
	DisplayName string `json:"displayName,omitempty"`
	Type        string `json:"type"` // string|number|boolean|object|array
	Required    bool   `json:"required,omitempty"`
	Description string `json:"description,omitempty"`
}

PropSpec describes one input property of an action/trigger. It is the ONE prop shape shared by the connector framework (connector.go), the catalogue, and the MCP tool input-schema derivation (mcp.go) — one definition, three consumers.

type RunContext ¶

type RunContext struct {
	Org         string
	Input       map[string]any
	PrevOutputs map[string]any
	Token       func(secretName string) ([]byte, error)
}

RunContext is what an action's Run receives. It is the connector's ENTIRE view of the world: the org (for logging/attribution only — never a place to widen scope), the resolved input, the prior steps' outputs (threaded), and Token — the ONLY door to a credential. Token is bound at dispatch time to the VALIDATED org (StepInput.Owner) and the connector's own provider id, so a connector can reach no other tenant's and no other provider's secret.

type RunEndInput ¶

type RunEndInput struct {
	RunID  string `json:"runId"`
	Owner  string `json:"owner"`
	Status string `json:"status"`
}

RunStartInput / RunEndInput are the durable run-bookkeeping activity payloads. The durable path is the SINGLE owner of run bookkeeping (MED-1): whichever entrypoint drives a workflow — manual /run, MCP, or a scheduled cron tick — records the run exactly once here, so metering/audit never double-count and every execution lands a FlowRun row visible to listRuns/getRun.

type RunStartInput ¶

type RunStartInput struct {
	RunID         string `json:"runId"`
	Owner         string `json:"owner"`
	FlowID        string `json:"flowId"`
	FlowVersionID string `json:"flowVersionId"`
}

RunStartInput / RunEndInput are the durable run-bookkeeping activity payloads. The durable path is the SINGLE owner of run bookkeeping (MED-1): whichever entrypoint drives a workflow — manual /run, MCP, or a scheduled cron tick — records the run exactly once here, so metering/audit never double-count and every execution lands a FlowRun row visible to listRuns/getRun.

type StepInput ¶

type StepInput struct {
	Owner       string         `json:"owner"`
	RunID       string         `json:"runId"`
	Name        string         `json:"name"`
	PieceName   string         `json:"pieceName"`
	ActionName  string         `json:"actionName"`
	Input       map[string]any `json:"input"`
	PrevOutputs map[string]any `json:"prevOutputs"`
}

StepInput is the activity's per-step input. Owner is copied verbatim from FlowRunInput.Owner by the workflow — an activity can never widen its own scope.

type StepOutput ¶

type StepOutput struct {
	Name   string `json:"name"`
	Output any    `json:"output"`
}

StepOutput is the activity's result for one step.

func ExecuteStepActivity(ctx context.Context, in StepInput) (StepOutput, error)

type StepSettings ¶

type StepSettings struct {
	PieceName    string         `json:"pieceName,omitempty"`
	PieceVersion string         `json:"pieceVersion,omitempty"`
	ActionName   string         `json:"actionName,omitempty"`
	TriggerName  string         `json:"triggerName,omitempty"`
	Input        map[string]any `json:"input,omitempty"`
}

StepSettings is the flattened union of PieceTriggerSettings / PieceActionSettings / CodeActionSettings — the fields the engine actually reads to dispatch a step: which piece, which action/trigger, and the input map. (The builder-only settings — propertySettings, sampleData, errorHandlingOptions — round-trip opaquely via the raw version JSON in the store; they are not modeled here.)

type Store ¶

type Store struct {
	// contains filtered or unexported fields
}

Store is the automations database. ONE SQLite file ({DataDir}/automations.db) holds every org's flows, versions, and runs; tenant isolation is the `org` column, physical on EVERY uniqueness + lookup index (each leads with org). MaxOpenConns(1) serializes writes against the single-writer WAL file.

func (s *Store) ClaimMeter(ctx context.Context, org, id string) (bool, error)

func (s *Store) Close() error

func (s *Store) CountRunsSince(ctx context.Context, org string, since int64) (int, error)

func (s *Store) CreateFlow(ctx context.Context, f Flow) (Flow, error)

func (s *Store) CreateRun(ctx context.Context, r FlowRun) (FlowRun, error)

func (s *Store) CreateRunIfAbsent(ctx context.Context, r FlowRun) (bool, error)

func (s *Store) CreateVersion(ctx context.Context, v FlowVersion) (FlowVersion, error)

func (s *Store) DeleteFlow(ctx context.Context, org, id string) (bool, error)

func (s *Store) DeleteFlowTriggers(ctx context.Context, org, flowID string) error

func (s *Store) DeleteRun(ctx context.Context, org, id string) error

func (s *Store) GetFlow(ctx context.Context, org, id string) (Flow, error)

func (s *Store) GetRun(ctx context.Context, org, id string) (FlowRun, error)

func (s *Store) GetVersion(ctx context.Context, org, id string) (FlowVersion, error)

func (s *Store) LatestVersion(ctx context.Context, org, flowID string) (FlowVersion, error)

func (s *Store) ListFlows(ctx context.Context, org string, limit int) ([]Flow, error)

func (s *Store) ListRuns(ctx context.Context, org, flowID string, limit int) ([]FlowRun, error)

func (s *Store) ListVersions(ctx context.Context, org, flowID string, limit int) ([]FlowVersion, error)

func (s *Store) MatchTriggers(ctx context.Context, org, provider, event string) ([]triggerSub, error)

func (s *Store) UpdateFlow(ctx context.Context, f Flow) (Flow, error)

func (s *Store) UpdateRunStatus(ctx context.Context, org, id string, status FlowRunStatus, finish, updated int64) error

func (s *Store) UpdateVersion(ctx context.Context, v FlowVersion) (FlowVersion, error)

func (s *Store) UpsertTrigger(ctx context.Context, org, provider, event, flowID, versionID string) error

type Trigger ¶

type Trigger struct {
	Name        string
	DisplayName string
	Description string
	Strategy    TriggerStrategy
	Props       []PropSpec
}

Trigger is one entry point of a connector. Strategy selects POLLING (cron) vs WEBHOOK vs MANUAL. Phase-1 triggers are catalogue/metadata only (the entry wiring lives in the flow's root trigger + enable/disable); a Trigger carries no Run.

type TriggerEvent ¶

type TriggerEvent struct {
	Source    string         // provider slug == the flow trigger's pieceName ("github","stripe","slack",…)
	Name      string         // event name == the flow trigger's triggerName ("push","charge","message",…)
	DedupeKey string         // idempotency key; "" ⇒ every delivery is its own run
	Depth     int            // causation depth (in-platform hops so far); 0 = external origin
	Payload   map[string]any // the event body, readable by actions as {{trigger.field}}
}

TriggerEvent is the ONE inbound shape every trigger source hands to Deliver. Source/Name select which flows fire (they equal a flow trigger's pieceName / triggerName); Payload is threaded into each run as {{trigger.*}}; DedupeKey makes a re-delivered event idempotent (a flow fires at most once per DedupeKey); Depth is the causation depth (0 = external origin), propagated by in-platform producers so a cycle terminates.

type TriggerStrategy ¶

type TriggerStrategy string

TriggerStrategy mirrors trigger/index.ts TriggerStrategy. It selects HOW a flow starts: POLLING → a cron schedule on the tasks engine; WEBHOOK/APP_WEBHOOK → an inbound HTTP event; MANUAL → an explicit /run.

const (
	StrategyPolling    TriggerStrategy = "POLLING"
	StrategyWebhook    TriggerStrategy = "WEBHOOK"
	StrategyAppWebhook TriggerStrategy = "APP_WEBHOOK"
	StrategyManual     TriggerStrategy = "MANUAL"
)

type UpdateActionRequest ¶

type UpdateActionRequest struct {
	Name     string       `json:"name"`
	Type     string       `json:"type"`
	Settings StepSettings `json:"settings"`
}

UpdateActionRequest replaces the settings of the step named Name.

type UpdateTriggerRequest ¶

type UpdateTriggerRequest FlowTrigger

UpdateTriggerRequest replaces the root trigger node.