apps 0.0.1-beta.1 → 0.0.1-beta.100

package/types/apps/src/contracts/events.d.ts

@@ -0,0 +1,94 @@
+/**
+ * App events. An app declares the events it emits beside its account requirements, so a host
+ * reads them without evaluating the app. Handlers emit occurrences; the host keeps them only
+ * when the invocation that emitted them succeeds, then delivers them to its subscribers.
+ */
+import { Schema } from "effect";
+/** Dotted lower-case words, such as `issue.opened`. Hosts prefix them with the app's slug. */
+export declare const EventName: Schema.String;
+export type EventName = typeof EventName.Type;
+/** A filter value: subscribers match an occurrence by equal scalars. */
+export declare const EventFilterValue: Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>;
+export type EventFilterValue = typeof EventFilterValue.Type;
+/** Size and count limits for events; bytes are UTF-8 bytes of the JSON text. */
+export declare const EventLimits: Schema.Struct<{
+    /** An occurrence's `data`, leaving room under a 256 KiB delivery for its envelope. */
+    readonly maxDataBytes: Schema.Int;
+    readonly maxEventsPerInvocation: Schema.Int;
+    readonly maxDescriptionLength: Schema.Int;
+    readonly maxIdLength: Schema.Int;
+}>;
+export type EventLimits = typeof EventLimits.Type;
+export declare const defaultEventLimits: {
+    readonly maxDataBytes: number;
+    readonly maxEventsPerInvocation: number;
+    readonly maxDescriptionLength: number;
+    readonly maxIdLength: number;
+};
+/** One event as the host reads it from an app's requirements. Both schemas are JSON Schema. */
+export declare const DeclaredEvent: Schema.Struct<{
+    readonly description: Schema.String;
+    /** An object of scalar fields. Subscribers may name any of them to narrow an event. */
+    readonly filters: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    /** The shape of each occurrence's `data`. */
+    readonly payload: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>;
+export type DeclaredEvent = typeof DeclaredEvent.Type;
+/** An app's declared events, by name. */
+export declare const DeclaredEvents: Schema.$Record<Schema.String, Schema.Struct<{
+    readonly description: Schema.String;
+    /** An object of scalar fields. Subscribers may name any of them to narrow an event. */
+    readonly filters: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    /** The shape of each occurrence's `data`. */
+    readonly payload: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>>;
+export type DeclaredEvents = typeof DeclaredEvents.Type;
+/**
+ * One occurrence an invocation emitted. `id` is the stable identifier subscribers deduplicate on,
+ * such as the provider's delivery ID. `account` is the account the event came from, or null for
+ * an app without accounts.
+ */
+export declare const EmittedEvent: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly id: Schema.String;
+    /** Milliseconds since the epoch when the event happened. */
+    readonly occurredAt: Schema.Int;
+    readonly data: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly filters: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>;
+    readonly account: Schema.NullOr<Schema.brand<Schema.String, "acc">>;
+}>;
+export type EmittedEvent = typeof EmittedEvent.Type;
+/** What a successful invocation emitted, in order. */
+export declare const EmittedEvents: Schema.$Array<Schema.Struct<{
+    readonly name: Schema.String;
+    readonly id: Schema.String;
+    /** Milliseconds since the epoch when the event happened. */
+    readonly occurredAt: Schema.Int;
+    readonly data: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly filters: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>;
+    readonly account: Schema.NullOr<Schema.brand<Schema.String, "acc">>;
+}>>;
+/** Native event declaration. Filters are named scalar fields; the payload is any JSON schema. */
+export interface AppEvent {
+    readonly description: string;
+    readonly filters: Readonly<Record<string, Schema.Decoder<unknown>>>;
+    readonly payload: Schema.Decoder<unknown>;
+}
+/** Options for one emitted occurrence. */
+export interface EmitOptions<Filters> {
+    /** Values subscribers filter on. Required when the event declares filters. */
+    readonly filters?: Filters;
+    /**
+     * A stable identifier, such as the provider's delivery or record ID, so a repeated delivery of
+     * the same upstream event is not delivered twice. Defaults to a random ID.
+     */
+    readonly id?: string | undefined;
+    /** When the event happened. Defaults to now. */
+    readonly occurredAt?: Date | number | undefined;
+    /**
+     * The ID of the account the event came from. A webhook handler defaults to its source account,
+     * and an invocation with exactly one of the caller's accounts to that account; the app's own
+     * accounts never count. Name it when there are several.
+     */
+    readonly account?: string | undefined;
+}

package/types/apps/src/contracts/failure.d.ts

@@ -0,0 +1,54 @@
+/** Failure detail that crosses the runtime boundary to the app's own caller. */
+import { Schema } from "effect";
+/** Longest failure message carried across the runtime boundary. */
+export declare const maxFailureMessageLength = 2048;
+/**
+ * `app` for errors thrown by authored code, `storage` for app data failures the host raised, and
+ * `service` for an external API the app called through a framework helper.
+ */
+export declare const FailureSource: Schema.Literals<readonly ["app", "storage", "service"]>;
+/** The thrown error's name, such as `TypeError`, or the host error's tag. */
+export declare const FailureName: Schema.String;
+/** A stable host failure code, such as an app data reason, or the thrown error's own `code`. */
+export declare const FailureCode: Schema.String;
+/** Bounded, with the invocation's account secrets replaced. */
+export declare const FailureMessage: Schema.String;
+/** Most fields of one thrown error carried across the runtime boundary. */
+export declare const maxFailureFields = 8;
+/** Longest text field value carried across the runtime boundary. */
+export declare const maxFailureFieldLength = 256;
+/** A field name as the error's code spells it, such as `reason` or `pointer`. */
+export declare const FailureFieldName: Schema.String;
+/** Bounded text with account secrets replaced, a finite number, or a boolean. */
+export declare const FailureFieldValue: Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>;
+/**
+ * The thrown error's own scalar fields beside its name, code and message, such as the `reason`
+ * and `pointer` a spec compiler sets. Nested values, stacks and causes are never carried.
+ */
+export declare const FailureFields: Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>;
+export type FailureFields = typeof FailureFields.Type;
+/**
+ * The error an app's own code raised, or the specific host failure it hit. Stacks and cause
+ * values stay private. Builds from before these fields existed send none.
+ */
+export declare const FailureDetail: {
+    source: Schema.optionalKey<Schema.Literals<readonly ["app", "storage", "service"]>>;
+    errorName: Schema.optionalKey<Schema.String>;
+    code: Schema.optionalKey<Schema.String>;
+    message: Schema.optionalKey<Schema.String>;
+    fields: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>>;
+};
+/** Longest error message a service stated, as carried across the runtime boundary. */
+export declare const maxUpstreamMessageLength = 1024;
+/**
+ * The error a service stated in its own response: a JSON-RPC error's code and message, or an
+ * OAuth Bearer error code and description. Bounded, with the invocation's account secrets replaced.
+ */
+export declare const UpstreamError: Schema.Struct<{
+    readonly code: Schema.Union<readonly [Schema.Int, Schema.String]>;
+    readonly message: Schema.optionalKey<Schema.String>;
+}>;
+export type UpstreamError = typeof UpstreamError.Type;
+/** Where a service failed: setting up a session, listing tools, or running one. */
+export declare const FailurePhase: Schema.Literals<readonly ["connect", "discover", "call"]>;
+export type FailurePhase = typeof FailurePhase.Type;

package/types/apps/src/contracts/graphql.d.ts

@@ -1,4 +1,5 @@
 import type { ProviderError } from "./provider-error.js";
+import type { NetworkRefused } from "./network.js";
 /** GraphQL discovery contracts. Catalogs are evaluated with the selected account. */
 import { Schema, type Effect } from "effect";
 import { type JsonValue } from "./schema.js";
@@ -97,7 +98,7 @@ export interface GraphqlTool {
     readonly description: string;
     readonly readOnly: boolean;
     readonly input: Schema.Decoder<JsonValue>;
-    readonly run: (context: unknown, input: JsonValue) => Effect.Effect<JsonValue, GraphqlError | ProviderError>;
+    readonly run: (context: unknown, input: JsonValue) => Effect.Effect<JsonValue, GraphqlError | ProviderError | NetworkRefused>;
 }
 /** One tool per root field; subscriptions require a separate long-lived host. */
 export type GraphqlTools = Readonly<Record<string, GraphqlTool>>;