core

func (DeliveryTicket) URL ¶

func (t DeliveryTicket) URL(relativeKey string) (string, error)

URL returns the delivery URL for one object, addressed RELATIVE to the ticket's prefix. relativeKey is the tail: for a ticket on "_gated/videos/v1/transcodes/j1/720p/" that is "seg_000042.ts".

It never returns a URL without the credential attached — a ticket that somehow reached a caller unarmed is an error, not a public URL.

func (*Dependency) Select ¶

func (d *Dependency) Select(table string) *DependencyQuery

Select starts a structured read of one exposed table. name is the LOGICAL table name the producer declared via ms.ExposeTable (e.g. "users") — lowercase snake_case, never the physical prefixed relation name.

func (*DependencyQuery) Columns ¶

func (q *DependencyQuery) Columns(cols ...string) *DependencyQuery

Columns restricts the projection to the named columns. Accumulates across calls; at most 64 names. An empty projection is resolved by the read-exposed PROXY only, which expands it to all visible columns; the deployed plane and a co-located dev read both require at least one column — the blessed dynamic-SELECT builder never emits SELECT *.

func (*DependencyQuery) Limit ¶

func (q *DependencyQuery) Limit(n int) *DependencyQuery

Limit caps the row count. The platform defaults to 200 when unset (or <= 0) and hard-caps at 2000; a read cut at the limit reports Truncated=true via Result.

func (*DependencyQuery) Result ¶

func (q *DependencyQuery) Result(ctx context.Context) (*DependencyResult, error)

Result executes the read and returns rows plus the Truncated flag. Failure modes are typed and fail-closed (never silently empty) — see the Err* sentinels.

func (*DependencyQuery) Rows ¶

func (q *DependencyQuery) Rows(ctx context.Context) ([]map[string]any, error)

Rows executes the read and returns the decoded rows — one map per row, column name to value. Numeric values decode as json.Number (not float64) so int64 join keys keep full fidelity for the fetch-then-join in app code. Rows is never nil on success. When the read hits the limit the extra rows are simply absent here — use Result if you need the Truncated flag.

func (*DependencyQuery) Where ¶

func (q *DependencyQuery) Where(col string, value any) *DependencyQuery

Where adds an equality predicate: col = value. value must be a JSON scalar (string, bool, or a numeric type) — the proxy's filter language is exactly scalar equality and scalar IN, nothing else (no NULL matching, no ranges, no nesting). Predicates across columns are ANDed; at most 16 filter columns, one predicate per column.

func (*DependencyQuery) WhereIn ¶

func (q *DependencyQuery) WhereIn(col string, values ...any) *DependencyQuery

WhereIn adds an IN predicate: col IN (values...). 1..200 JSON scalar values; an empty list is rejected (an always-false predicate is almost certainly a bug — fail fast rather than return silently empty rows).

func (*Module) AbsorbInfra ¶

func (m *Module) AbsorbInfra()

AbsorbInfra declares that this module passes EVERY platform infrastructure metric through to the app owner at a price of 0 — compute, egress, storage, AI tokens, and whatever the platform meters next. Use it when the module bills its customer through its OWN meters and adds no infrastructure passthrough on top.

🔴 THE MODULE NAMES NOTHING. This is one manifest flag; the platform expands it against its own metric catalog at publish, so a metric introduced after this module shipped is absorbed with no republish. The alternative — a Meter("infra.X", Price(0)) line per metric — is a copy of a catalog the module does not own, and it has already gone stale once: infra.compute.ms was re-chartered to infra.compute.walltime.ms and then deleted, so every module still naming it declared nothing at all.

An explicit Meter("infra.X", Price(n)) is applied AFTER the absorb and WINS:

ms.AbsorbInfra()                                       // baseline: all infra at 0
ms.Meter("infra.egress.api.bytes", ms.Price(120_000))  // …except egress

Absorbing changes what the APP OWNER is billed for that metric. It does not make the underlying cost disappear.

func (*Module) Cache ¶

func (m *Module) Cache(ctx context.Context) (cache.Cacher, func(), error)

Cache returns a scoped cache client. Keys are auto-prefixed with {appID}:{moduleID}:.

c, release, err := mod.Cache(r.Context())
if err != nil { ... }
defer release()
c.Set(ctx, "views:123", "42", 5*time.Minute)
val, err := c.Get(ctx, "views:123")

func (*Module) Call ¶

func (m *Module) Call(ctx context.Context, targetModuleID, method, path string, body, out any) error

Call makes one server-mediated module-to-module hop through the platform dispatch. It marshals body to JSON (omitted for a nil body), POST/GET/etc to the resolved dispatch URL scoped to the current app, and decodes the JSON response into out (skipped when out is nil).

The app id is read from the request context (auth.Get) — the same identity the SDK injects for handlers — and sent as X-MS-App-ID so the dispatch can resolve the install. X-MS-Service-Secret carries this CALLING module's live session/deploy credential, allowing dispatch to authenticate which installed module initiated the internal hop. The caller never holds the CALLEE's credentials: dispatch injects the target module's per-session token and identity before forwarding.

path must include its leading slash and any raw query string, e.g. "/internal/exchange" or "/platform/users?limit=10". A verified actor delegation is forwarded only to a canonical /platform route. Public and Internal calls remain actorless service calls even when they originate in a Platform handler.

DEV/DISPATCH TRANSPORT — see resolveCallURL for the prod (#146) seam.

func (*Module) CallDependency ¶

func (m *Module) CallDependency(ctx context.Context, producerRef, method, path string, body, out any) error

CallDependency addresses a declared dependency by the same stable ref used in DependsOn. The platform authenticates this module, checks the live dependency declaration, resolves the producer within the current app, and forwards an actorless request to the producer's Internal surface.

func (*Module) CallDependencyPost ¶

func (m *Module) CallDependencyPost(ctx context.Context, producerRef, path string, body, out any) error

CallDependencyPost is CallDependency specialized to POST with a JSON body.

func (*Module) CallGet ¶

func (m *Module) CallGet(ctx context.Context, targetModuleID, path string, out any) error

CallGet is Call specialized to GET (no request body). path carries any raw query string, e.g. "/internal/users?limit=10".

func (*Module) CallPost ¶

func (m *Module) CallPost(ctx context.Context, targetModuleID, path string, body, out any) error

CallPost is Call specialized to POST with a JSON body.

func (*Module) CallWithOptions ¶

func (m *Module) CallWithOptions(ctx context.Context, targetModuleID, method, path string, body, out any, options CallOptions) error

CallWithOptions is Call with opt-in response bounds and strict JSON decoding. A negative MaxResponseBytes is rejected before any network I/O. When out is nil, a successful response body is not read or decoded.

func (*Module) CancelTask ¶

func (m *Module) CancelTask(ctx context.Context, jobID string) error

CancelTask requests monotonic cancellation of a local or managed job. Cancellation is idempotent for queued, running, already-cancelled, and terminal jobs.

func (*Module) Close ¶

func (m *Module) Close()

Close cleans up resources.

func (*Module) Config ¶

func (m *Module) Config() Config

func (*Module) ContributesTo ¶

func (m *Module) ContributesTo(hostSpec, slot string, payload any)

ContributesTo declares that this module pushes payload INTO another module's contribution slot — the contributor side of Provide. It is a ZERO-RUNTIME declaration that mirrors DependsOn: the payload becomes manifest metadata (contributesTo), and the platform catalog — or the CLI dev runner in local dev — performs the actual registration into the host after app-owner approval. The module's binary never calls the host directly.

hostSpec takes the same id or id@constraint form as DependsOn, and for the same reason: a contribution couples you to the host's declared SLOT surface exactly as a dependency couples you to its API, and a host may reshape or remove a slot on any version bump — the pinned range is what lets the catalog refuse a contribution against a host version that no longer declares the slot. Pair it with ms.DependsOn(hostSpec) so the platform installs the host first and can validate the slot against the host's provides.

payload must be a JSON-serializable value matching the host slot's declared type (e.g. oauth-core's AuthProvider). Re-declaring the same (host, slot) replaces the payload and the constraint — last call wins.

Panics on an empty host/slot, a host id or SemVer constraint that does not parse, or an unmarshalable payload — all programmer error, caught at startup rather than shipping a manifest entry nobody can resolve.

ms.ContributesTo("oauth-core@^1.2", "auth-provider", AuthProvider{
    Slug: "google", Name: "Google", Icon: "login",
    AuthorizeURL: "/authorize-url", CallbackURL: "/callback",
})

func (*Module) Cron ¶

func (m *Module) Cron(name, schedule string, handler http.HandlerFunc)

Cron registers a handler to run on a cron schedule. The handler is mounted on this module's Internal scope at /__mirrorstack/crons/{name}. The schedule is recorded in the manifest so the platform's scheduler knows what URL to POST when the cron fires.

The schedule string is passed through to the platform unchanged — validation happens platform-side so module developers see one error format regardless of the scheduler implementation.

Names must not contain path separators (/, \), whitespace, dot-segments (..), or null bytes. Do not rely on r.RemoteAddr to identify the scheduler; in Lambda + API Gateway it is always the AGW IP. Call from startup code, not a request handler.

Panics on empty schedule, an invalid name, or duplicate name registration.

mod.Cron("cleanup-temp", "0 3 * * *", cleanupHandler)

func (*Module) DB ¶

func (m *Module) DB(ctx context.Context) (db.Querier, func(), error)

DB returns a scoped database connection.

Production: uses per-app credentials injected by the platform via Lambda payload. Dev: uses DATABASE_URL env var with localhost fallback. Dev connections are wrapped with the cross-module fail-fast guard (db_guard.go): a raw query against another module's tables errors immediately instead of silently succeeding in the shared dev database — use ms.DependencyDB for that.

conn, release, err := mod.DB(r.Context())
if err != nil { ... }
defer release()
conn.QueryRow(ctx, "SELECT ...").Scan(&v)

func (*Module) DependencyDB ¶

func (m *Module) DependencyDB(ctx context.Context, producerRef string) *Dependency

DependencyDB returns a read handle on producerRef's exposed tables within the current app. producerRef accepts the same module ref forms as ms.DependsOn — "@owner/slug", bare "slug", the m<hex> module ID, or a dashed UUID; a trailing @<version-constraint> is tolerated and ignored (reads always target the version the producer actually runs, which the platform resolves). The app scope is read from ctx via the SDK's auth identity — callers don't pass it and cannot forge it.

The returned handle only builds STRUCTURED reads (Select/Columns/Where/ WhereIn/Limit). It is not a *pgx pool and never will be — see the package comment for why raw cross-plane SQL cannot exist.

func (*Module) DependsOn ¶

func (m *Module) DependsOn(spec string, configure ...func(*Need))

DependsOn declares a REQUIRED dependency on another module. Install fails if no published version of the dep matches the constraint.

Spec syntax: "<id>" (any version) or "<id>@<constraint>" where constraint is an npm-style SemVer range. The id may be bare (`oauth-core`) or owner-prefixed (`@anna/oauth`). Examples:

ms.DependsOn("@anna/oauth")              // any version
ms.DependsOn("@anna/oauth@^1.2.0")       // >=1.2.0, <2.0.0
ms.DependsOn("@anna/oauth@1.2.3")        // exact
ms.DependsOn("oauth-core@>=1.2 <2")      // bare id, range

Optional configure callbacks declare what the consumer wants from the dep — relation reads and event subscriptions:

ms.DependsOn("@anna/oauth@^0.4.0", func(n *ms.Need) {
    n.Table("oauth_users")
    n.Event("user_signed_in")
})

The catalog validates each Table name against the dep's `mod_<id>` schema and each Event name against the dep's manifest at install time; after app-owner approval, the platform issues one GRANT SELECT per Table and wires event routing per Event.

Panics on an invalid SemVer constraint — programmer error, not runtime input.

For OPTIONAL deps (the consumer's handler only runs when the dep is installed — typically an event subscription), use ms.OptionalDependOn inside the handler-registration call.

func (*Module) DrainAudit ¶

func (m *Module) DrainAudit(ctx context.Context) error

DrainAudit forwards at most one bounded batch from the current app's audit outbox. Rows are leased with a rotating fence, so callers may safely run this concurrently from post-commit hooks, cron handlers, and maintenance jobs.

Delivery is at-least-once. API Platform de-duplicates EventID within the invocation-proven app and module stream.

func (*Module) Emit ¶

func (m *Module) Emit(ctx context.Context, name string, payload any) error

Emit publishes an event to every LIVE module that subscribes to name within the current app. It wraps payload in the event envelope (a fresh UUID id, the emitting module's Config.ID as sourceModuleID, and an RFC3339 UTC sentAt), then POSTs the envelope to the platform dispatch event bus scoped to the current app. The dispatch fans the SAME envelope out to each subscriber session — the emitter never addresses subscribers directly.

The app id is read from the request context (auth.Get) — the same identity the SDK injects for handlers — and is encoded in the dispatch URL. An empty app id is an error (no panic): Emit needs an app scope to know which installs can receive the event.

Delivery is AT-LEAST-ONCE and best-effort per subscriber (the dispatch logs per-subscriber failures and never fails the whole call); subscriber handlers must be idempotent. A non-2xx response from the dispatch itself is returned as an error with the response body truncated to ~2 KB.

DEV/DISPATCH TRANSPORT — see resolveEventBusURL for the prod (#146) seam.

func (*Module) Emits ¶

func (m *Module) Emits(name string)

Emits declares that this module emits an event of the given name. The declaration appears in the manifest's events.emits list so the platform knows the event belongs to this module's vocabulary and other modules can subscribe to it. Runtime emission is a separate API (TBD); this method is purely a declaration.

Panics on an invalid name (see OnEvent for the rules) or duplicate declaration. Call from startup code.

func (*Module) ExposeTable ¶

func (m *Module) ExposeTable(name string)

ExposeTable marks one of this module's per-app tables as eligible to be read (SELECT) by a depending module installed in the same app. Declare the bare table name; the platform resolves it to the physical form — app_<id>."<prefix><table>" in each app's tenant schema — when granting. It is a pure DECLARATION — no runtime, no return value — recorded in the manifest under `exposes.tables` so the platform catalog can issue GRANT SELECT after the app owner approves a dependency. Cross-app module state (the mod_<id> schema) is NOT shareable this way.

v1 is TABLES ONLY, read-only. The producer marks a table READABLE; it does NOT name WHO reads it. The app owner — the trust root — decides which installed modules may read by approving their declared dependency. There is intentionally no per-consumer allowlist here: a marketplace's consumers are third parties, so a publisher-controlled reader list is the wrong trust model.

Panics on an empty or otherwise invalid table identifier (lowercase, leading letter, [a-z0-9_], <=63 chars). Call from startup code, not a request handler.

ms.ExposeTable("orders")

func (*Module) Internal ¶

func (m *Module) Internal(fn func(r chi.Router))

Internal registers routes with internal auth scope (platform-to-module only). Auto-mounted under /internal/ — write `r.Post("/sessions", ...)` and the route lands at /internal/sessions. Validates X-MS-Internal-Secret via constant-time comparison. The middleware is cached on the Module at New() so OnEvent / Cron registrations reuse a single closure instead of constructing one per call.

func (*Module) Meter ¶

func (m *Module) Meter(name string, opts ...meter.MetricOption)

Meter DECLARES a usage metric. Call it once, up front (startup code), per metric — exactly like Emits / RegisterPermission: it registers the metric as a SIDE EFFECT and returns NOTHING. The declaration (kind + unit + price) is recorded in the manifest so the platform's metric catalog is authoritative before any event arrives, AND in the meter client's by-name registry so Record can resolve the metric.

The kind is an OPTION: meter.Counter (additive; the platform SUMs) or meter.Gauge (absolute level; the platform takes MAX or a time-weighted integral, never a SUM). meter.Unit / meter.Price set the unit and the per-unit customer price (both optional). meter.BySubject is valid only with Gauge and declares SUM(MAX(value) per observation subject).

Emit at runtime with the package-level Record(ctx, name, value) — BY NAME, mirroring Emits/Emit. A custom metric MUST pass exactly one kind option; a reserved infra.*/platform.* metric may carry meter.Price ONLY (kind/unit/ aggregation are platform-owned). Panics on a duplicate name, an invalid name, conflicting kinds, a missing kind on a custom metric, BySubject without Gauge, or a kind/unit/aggregation on a reserved name. Like the other Module resource methods, it requires New() to have returned successfully — calling it on a zero Module panics on the nil meterClient (the package-level wrapper's mustDefault guards the before-Init case).

ms.Meter("orders.placed", ms.Counter, ms.Unit("order"), ms.Price(50_000))
ms.Meter("users.active", ms.Gauge, ms.BySubject, ms.Unit("user"))
ms.Meter("infra.compute.walltime.ms", ms.Price(0)) // reserved price-override

To zero EVERY platform infra metric at once — the usual want for a module that charges through its own meters — call AbsorbInfra instead of listing them. A metric name written here is a copy of the platform's catalog and goes stale the first time the platform renames one (infra.compute.ms already did).

func (*Module) ModuleDB ¶

func (m *Module) ModuleDB(ctx context.Context) (db.Querier, func(), error)

ModuleDB returns a connection scoped to this module's shared schema (mod_<id>). Use it for cross-app state — outbox tables, dedup ledgers, cross-app audit logs, rate limiters, module-wide config — anything a module needs that is owned by the module rather than by a single app.

Production: uses the per-module credential injected by the platform via db.WithModuleCredential. Independent of the per-app credential read by Module.DB — a handler that needs both gets both, in the same context.

Dev: shares the dev pool from DATABASE_URL with Module.DB; the schema is the only difference. The dev Postgres must have a mod_<id> schema for the queries to succeed.

The module schema overlays any app schema set on the caller's context for this single call only — the caller's ctx is not mutated, so a subsequent Module.DB call sees the original app schema unchanged.

conn, release, err := mod.ModuleDB(r.Context())
if err != nil { ... }
defer release()
conn.Exec(ctx, "INSERT INTO outbox(...) VALUES(...)")

func (*Module) ModuleTx ¶

func (m *Module) ModuleTx(ctx context.Context, fn func(q db.Querier) error) error

ModuleTx runs fn inside a transaction scoped to the module's shared schema (mod_<id>). Commits on success, rolls back on error or panic. Use this for the outbox-pattern: insert the work record AND the dedup row in the same transaction so the worker only ever sees consistent state.

err := mod.ModuleTx(r.Context(), func(q db.Querier) error {
    queries := generated.New(q)
    if err := queries.InsertOutbox(ctx, ...); err != nil { return err }
    return queries.MarkProcessed(ctx, ...)
})

func (*Module) Notify ¶

func (m *Module) Notify(ctx context.Context, n Notification) error

Notify sends an in-app notification to the current app's members. It resolves the Notification's i18n Labels to per-locale maps, wraps them in the notification envelope (a fresh UUID id, the sending module's Config.ID as sourceModuleID, and an RFC3339 UTC sentAt), then POSTs the envelope to the platform dispatch notification ingress scoped to the current app. The dispatch re-derives the sender identity from the live session — the envelope's sourceModuleID is informational, never trusted.

The app id is read from the request context (auth.Get) — the same identity the SDK injects for handlers — and is encoded in the dispatch URL. An empty app id is an error (no panic): Notify needs an app scope to know whose feed receives the notification.

Title is REQUIRED — a Title that resolves to no message (unset, or an empty literal) is an error (no panic). Body is optional (an unset Body sends an empty map). An unset Audience defaults to NotifyAdmins; any value other than NotifyAdmins/NotifyAllMembers is an error. A non-2xx response from the dispatch is returned as an error with the response body truncated to ~2 KB — never with the credential.

Works on both planes: under `mirrorstack dev --tunnel` the credential is the CLI's per-session secret; on a deployed module it is the per-module value the deploy provisioner injects. Both arrive as MS_INTERNAL_SECRET and are sent verbatim (see moduleSessionSecret).

func (*Module) OnEvent ¶

func (m *Module) OnEvent(name string, handler http.HandlerFunc, opts ...OnEventOption)

OnEvent registers handler for events of the given name from another module. Mounts on this module's Internal scope at /__mirrorstack/events/{name} and records the subscription in the manifest's events.subscribes map.

Optional dependency declarations co-locate via the variadic opts:

ms.OnEvent("@anna/billing/payment", onPayment,
    ms.OptionalDependOn("@anna/billing@^1", func(n *ms.Need) {
        n.Table("invoices")
    }))

Each OptionalDependOn-produced option appends an optional dep to the manifest. The dep is "scoped" to this handler in spirit — if the dep isn't installed, the event never fires and the handler never runs, so missing-dep failures are harmless.

The platform guarantees AT-LEAST-ONCE delivery — handlers must be idempotent or implement their own deduplication.

Names must not contain path separators (/, \), whitespace, dot-segments (..), or null bytes. Call from startup code (init / main), not from inside a request handler. Panics on duplicate registration.

func (*Module) OnTask ¶

func (m *Module) OnTask(name string, handler TaskHandler, opts ...TaskOption)

OnTask registers a background task handler. The handler appears in the manifest so the platform can admit managed task jobs. A dev HTTP endpoint is mounted at POST /__mirrorstack/tasks/{name} on the Internal scope for curl testing.

Names must not contain path separators (/, \), whitespace, dot-segments (..), or null bytes. Call from startup code (init / main), not from inside a request handler.

Panics on duplicate registration with the same name.

The execution class defaults to Standard — the module's own Lambda, with Lambda's 15-minute ceiling. Pass WithCompute to route the task to a heavier runner instead; the platform provisions it from the manifest at deploy.

mod.OnTask("thumbnail", thumbnailHandler, ms.WithTimeout(10*time.Minute))

mod.OnTask("transcode-video", transcodeHandler,
    ms.WithCompute(ms.Heavy(ms.Res{VCPU: 4, MemoryMB: 8192})),
    ms.WithTimeout(90*time.Minute),
    ms.WithMaxRetries(2),
)

func (*Module) Platform ¶

func (m *Module) Platform(fn func(r chi.Router))

Platform registers routes with platform auth scope. All routes declared inside fn are auto-mounted under /platform/ — write `r.Get("/users", ...)` and the route lands at /platform/users. Default role gate: admin only. Use Module.RequirePermission to open routes to member/viewer.

func (*Module) ProvideSlot ¶

func (m *Module) ProvideSlot(slot contributions.Slot)

built once at the call site and the Module just stores the resulting Slot.

func (*Module) Public ¶

func (m *Module) Public(fn func(r chi.Router))

Public registers routes with public auth scope (anyone, including anonymous). Auto-mounted under /public/ — write `r.Get("/me", ...)` and the route lands at /public/me.

func (*Module) Record ¶

func (m *Module) Record(ctx context.Context, name string, value float64) error

Record emits a usage event for the metric declared (via Meter) under name — BY NAME, mirroring Emit. Resolves the declared metric from the meter client's registry; returns an error (never panics) if name was never declared, or if value is negative/non-finite. A billing failure must never fail the handler, so the error should be logged, not propagated.

func (*Module) RecordObservation ¶

func (m *Module) RecordObservation(ctx context.Context, name string, value float64, observation meter.Observation) error

RecordObservation emits a v2 usage observation. Its caller-persisted event ID, subject, metadata, and occurrence time survive outbox retries; platform Dispatch still re-derives authoritative app/module/owner attribution. The SDK validates structure and normalizes OccurredAt to UTC without comparing it with the module process clock. API and Billing authoritatively decide the accepted occurrence window, replay outcome, and billing period.

func (*Module) RecordWithID ¶

func (m *Module) RecordWithID(ctx context.Context, eventID, name string, value float64) error

RecordWithID is Record with a caller-persisted UUID deduplication key. It is intended for transactional outboxes whose retries must remain idempotent.

func (*Module) RegisterPermission ¶

func (m *Module) RegisterPermission(name string, opts PermissionOpts)

RegisterPermission declares a module permission ONCE, recording its default role, custom roles, and resolved i18n Labels/Descriptions into this Module's registry so they appear in the manifest. Call it at startup (typically in a declare/ package) BEFORE the routes that gate on it. First-wins by name: re-declaring the same permission is a no-op.

Permission names are auto-namespaced with the module slug so two modules can each declare a "users.read" without colliding in the platform's catalog. Developers pass the SHORT name; the manifest stores "<slug>.<name>". If the caller already prefixed the name with the slug, the prefix is left alone.

import "github.com/mirrorstack-ai/app-module-sdk/roles"
ms.RegisterPermission("users.read", ms.PermissionOpts{
    DefaultRole: roles.Viewer(),
    Label:       ms.T("permissions.users.read"),
})

func (*Module) RegisterUI ¶

func (m *Module) RegisterUI(ui ModuleUI)

RegisterUI declares the module's UI surface — agent-visible Components plus DefaultPages mounted under /apps/<app-slug>/<module-slug>. See the ModuleUI doc comment for the shape. Validates the input and panics on programmer errors (duplicate names, invalid route, unknown prop type). Last-write-wins; a second call replaces the prior manifest.

ms.RegisterUI(ms.ModuleUI{
    Components: []ms.UIComponent{
        {Name: "SettingsForm", Export: "SettingsForm", Props: []ms.UIProp{
            {Key: "appId", Type: "text", Required: true},
        }},
    },
    DefaultPages: []ms.UIPage{
        {Route: "/", Title: "OAuth Settings", Export: "SettingsPage"},
    },
})

func (*Module) RequirePermission ¶

func (m *Module) RequirePermission(name string) func(http.Handler) http.Handler

RequirePermission returns chi middleware that gates a route on a permission declared via RegisterPermission, looked up BY NAME. It reads the registered permission's role set and enforces it (admin always passes). Call this at route registration time (alongside m.Platform/Public/Internal), NOT from inside a request handler.

import "github.com/mirrorstack-ai/app-module-sdk/roles"
// in declare/: ms.RegisterPermission("users.view", ms.PermissionOpts{DefaultRole: roles.Viewer()})
// in routes:
r.With(mod.RequirePermission("users.view")).Get("/items", listItems)

The name is slug-qualified the same way RegisterPermission qualifies it, so the short name used here matches the short name used there.

Safe-by-default: if the name was never RegisterPermission'd, it is registered lazily as ADMIN-ONLY (an isDev warning is logged) so a forgotten declaration locks the route down rather than opening it.

func (*Module) RequireStorage ¶

func (m *Module) RequireStorage()

RequireStorage opts this module into its per-app storage namespace. Call it once during startup before Start. The declaration is emitted in the manifest and is the platform's gate for vending temporary storage credentials.

func (*Module) Router ¶

func (m *Module) Router() *chi.Mux

func (*Module) RunTask ¶

func (m *Module) RunTask(ctx context.Context, name string, payload json.RawMessage) (string, error)

RunTask creates a task job and returns its job ID. Deployed requests contain only the caller's raw JSON payload; execution identity, resources, compute and artifacts are resolved by the platform. CLI dev mode instead enqueues the registered handler asynchronously in a process-local executor.

taskID, err := mod.RunTask(r.Context(), "transcode-video", payload)

func (*Module) RunTaskWithIdempotencyKey ¶

func (m *Module) RunTaskWithIdempotencyKey(ctx context.Context, name string, payload json.RawMessage, idempotencyKey string) (string, error)

RunTaskWithIdempotencyKey creates or recovers one logical task job. Persist the UUID with the caller's logical work before enqueueing, then reuse it after ambiguous failures or process restarts. Both the local executor and managed platform return the original job for an exact retry and reject key reuse with a different task or payload.

func (*Module) Start ¶

func (m *Module) Start() error

Lambda wins if both env vars are set (they are mutually exclusive in production but this ordering is a safety net).

func (*Module) Storage ¶

func (m *Module) Storage(ctx context.Context) (storage.Storer, error)

Storage returns a client always scoped to apps/<app>/<module>/.

s, err := mod.Storage(r.Context())
if err != nil { ... }
url, err := s.PresignPut(ctx, "photo.jpg", 15*time.Minute)
cdnURL, err := s.URL("photo.jpg")

Production enforces that scope with the IAM session policy on the vended credential; the client prefix is ergonomics, not a boundary. Dev mints the same policy shape and MinIO enforces it.

func (*Module) StoredContributions ¶

func (m *Module) StoredContributions(ctx context.Context, slot string) ([]contributions.Contribution, error)

StoredContributions returns the contributions OTHER modules have registered into one of THIS module's slots (slot key as declared via Provide), newest first. It reads the SDK-managed <moduleID>_contributions store — the canonical registry the platform's install-time auto-register writes to. Each entry's OwnerModuleID is the contributing module's canonical UUID, which a host can use to address that module. ID remains populated as a compatibility alias. Use this on the HOST side to consume contributions (e.g. oauth-core listing its registered auth providers).

A host installed before the SDK provisioned this store on install has no table for the app yet; the first read creates it (see Storage.WithTable) and returns empty, instead of failing the host with a missing-relation error it has no way to act on.

func (*Module) TaskStatus ¶

func (m *Module) TaskStatus(ctx context.Context, jobID string) (TaskJobStatus, error)

TaskStatus reads process-local state in CLI dev mode. Deployed jobs are scoped to the caller's app and this module; a sibling module cannot inspect them by guessing an ID.

func (*Module) Tx ¶

func (m *Module) Tx(ctx context.Context, fn func(q db.Querier) error) error

Tx runs fn inside a transaction with schema isolation. Commits on success, rolls back on error. The app schema is read from the caller's context (set by the platform's Lambda invoke shim via db.WithSchema). Compare with Module.ModuleTx which explicitly overlays the mod_<id> schema.

err := mod.Tx(r.Context(), func(q db.Querier) error {
    queries := generated.New(q)
    item, err := queries.GetItem(ctx, id)
    if err != nil { return err }
    return queries.DeductBalance(ctx, params)
})

func (*Need) Event ¶

func (n *Need) Event(name string)

Event records an event name the consumer subscribes to from this dep. Used by the catalog at install time to validate the event exists in the dep's manifest (Emits list) and to wire up routing.

ms.DependsOn("@bob/orders@^1", func(n *ms.Need) {
    n.Event("order_placed")
})

func (*Need) Table ¶

func (n *Need) Table(name string)

Table records a bare relation name from the dep's per-app tables as a SELECT request — the physical target is app_<id>."<prefix><table>" in the shared app tenant schema, not a cross-app mod_<id> schema. The catalog validates the name against the dep's exposed tables at install time; after app-owner approval, the platform issues GRANT SELECT against this consumer's per-app DB role.

ms.DependsOn("@anna/oauth@^0.4.0", func(n *ms.Need) {
    n.Table("oauth_users")
    n.Table("recent_orders")
})

func (*PermanentTaskError) Error ¶

func (e *PermanentTaskError) Error() string

func (*PermanentTaskError) Retryable ¶

func (e *PermanentTaskError) Retryable() bool

func (*PermanentTaskError) Unwrap ¶

func (e *PermanentTaskError) Unwrap() error