@vallum/standards 0.0.0-prerelease

package/dist/a2aPush.d.ts

@@ -0,0 +1,162 @@
+import { type A2ATask } from "./a2aTask.js";
+export interface A2APushNotificationAuthenticationInfo {
+    readonly schemes: readonly string[];
+}
+export interface A2ATaskPushNotificationConfig {
+    readonly id: string;
+    readonly taskId: string;
+    readonly url: string;
+    readonly createdAt: string;
+    readonly tenant?: string;
+    readonly authentication?: A2APushNotificationAuthenticationInfo;
+}
+export interface ListA2APushNotificationConfigsResult {
+    readonly configs: readonly A2ATaskPushNotificationConfig[];
+    readonly nextPageToken?: string;
+}
+export interface A2APushNotificationPayload {
+    readonly kind: "task";
+    readonly task: A2ATask;
+}
+export interface A2APushNotificationDeliveryRequest {
+    readonly method: "POST";
+    readonly url: string;
+    readonly headers: Record<string, string>;
+    readonly body: A2APushNotificationPayload;
+    readonly json: string;
+    readonly config: A2ATaskPushNotificationConfig;
+}
+export interface A2APushNotificationTransportResponse {
+    readonly status: number;
+}
+export type A2APushNotificationTransport = (request: A2APushNotificationDeliveryRequest) => A2APushNotificationTransportResponse | Promise<A2APushNotificationTransportResponse>;
+export interface A2APushHttpTransportOptions {
+    readonly allowedCallbackHosts?: readonly string[];
+    readonly fetch?: typeof fetch;
+    readonly timeoutMs?: number;
+}
+export interface A2APushNotificationDeliveryAttempt {
+    readonly configId: string;
+    readonly taskId: string;
+    readonly url: string;
+    readonly attemptNumber?: number;
+    readonly observedAt?: string;
+    readonly nextRetryAt?: string;
+    readonly status: "delivered" | "failed" | "skipped";
+    readonly httpStatus?: number;
+    readonly errorCode?: "A2A_PUSH_TRANSPORT_UNCONFIGURED" | "A2A_PUSH_TRANSPORT_FAILED";
+}
+export interface A2APushNotificationDeliveryResult {
+    readonly attempts: readonly A2APushNotificationDeliveryAttempt[];
+}
+export interface A2APushNotificationDeliveryQueueEntry {
+    readonly id: string;
+    readonly enqueuedAt: string;
+    readonly claimedAt?: string;
+    readonly completedAt?: string;
+    readonly failedAt?: string;
+    readonly status: "queued" | "claimed" | "completed" | "failed";
+    readonly request: A2APushNotificationDeliveryRequest;
+}
+export interface A2APushNotificationDeliveryQueueResult {
+    readonly entries: readonly A2APushNotificationDeliveryQueueEntry[];
+}
+export interface A2APushNotificationDeliveryWorkerResult {
+    readonly status: "empty" | "delivered" | "failed";
+    readonly entry?: A2APushNotificationDeliveryQueueEntry;
+    readonly attempt?: A2APushNotificationDeliveryAttempt;
+}
+export interface A2APushNotificationAttemptStore {
+    record(attempt: A2APushNotificationDeliveryAttempt): void;
+}
+export type A2APushNotificationErrorCode = "A2A_PUSH_CONFIG_INVALID" | "A2A_PUSH_CONFIG_NOT_FOUND" | "A2A_PUSH_URL_UNSAFE" | "A2A_PUSH_CREDENTIAL_STORAGE_UNSUPPORTED";
+export declare class A2APushNotificationError extends Error {
+    readonly code: A2APushNotificationErrorCode;
+    readonly status: 400 | 404;
+    constructor(code: A2APushNotificationErrorCode, message: string, status?: 400 | 404);
+}
+export declare class LocalA2APushNotificationStore {
+    #private;
+    put(config: A2ATaskPushNotificationConfig): A2ATaskPushNotificationConfig;
+    get(taskId: string, id: string): A2ATaskPushNotificationConfig | undefined;
+    list(taskId: string, pageSize?: number): ListA2APushNotificationConfigsResult;
+    delete(taskId: string, id: string): boolean;
+}
+export declare class LocalA2APushNotificationAttemptStore implements A2APushNotificationAttemptStore {
+    #private;
+    record(attempt: A2APushNotificationDeliveryAttempt): void;
+    list(): readonly A2APushNotificationDeliveryAttempt[];
+}
+export declare class JsonlA2APushNotificationAttemptStore implements A2APushNotificationAttemptStore {
+    #private;
+    constructor(filePath: string);
+    record(attempt: A2APushNotificationDeliveryAttempt): void;
+    list(): readonly A2APushNotificationDeliveryAttempt[];
+}
+export declare class JsonFileA2APushNotificationDeliveryQueue {
+    #private;
+    constructor(filePath: string);
+    enqueue(request: A2APushNotificationDeliveryRequest, options?: {
+        readonly id?: string;
+        readonly enqueuedAt?: Date;
+    }): A2APushNotificationDeliveryQueueEntry;
+    list(): readonly A2APushNotificationDeliveryQueueEntry[];
+    claim(options?: {
+        readonly now?: Date;
+    }): A2APushNotificationDeliveryQueueEntry | undefined;
+    complete(id: string, options?: {
+        readonly now?: Date;
+    }): boolean;
+    fail(id: string, options?: {
+        readonly now?: Date;
+    }): boolean;
+}
+export declare function createA2APushNotificationConfig(options: {
+    readonly store: LocalA2APushNotificationStore;
+    readonly taskId: string;
+    readonly value: unknown;
+    readonly allowedCallbackHosts?: readonly string[];
+    readonly now?: Date;
+}): A2ATaskPushNotificationConfig;
+export declare function getA2APushNotificationConfig(options: {
+    readonly store: LocalA2APushNotificationStore;
+    readonly taskId: string;
+    readonly id: string;
+}): A2ATaskPushNotificationConfig;
+export declare function listA2APushNotificationConfigs(options: {
+    readonly store: LocalA2APushNotificationStore;
+    readonly taskId: string;
+    readonly pageSize?: number;
+}): ListA2APushNotificationConfigsResult;
+export declare function deleteA2APushNotificationConfig(options: {
+    readonly store: LocalA2APushNotificationStore;
+    readonly taskId: string;
+    readonly id: string;
+}): {
+    readonly taskId: string;
+    readonly id: string;
+    readonly deleted: boolean;
+};
+export declare function deliverA2APushNotifications(options: {
+    readonly store: LocalA2APushNotificationStore;
+    readonly task: A2ATask;
+    readonly transport?: A2APushNotificationTransport;
+    readonly attemptStore?: A2APushNotificationAttemptStore;
+    readonly maxAttempts?: number;
+    readonly retryDelayMs?: number;
+    readonly now?: () => Date;
+}): Promise<A2APushNotificationDeliveryResult>;
+export declare function queueA2APushNotificationDeliveries(options: {
+    readonly store: LocalA2APushNotificationStore;
+    readonly task: A2ATask;
+    readonly queue: JsonFileA2APushNotificationDeliveryQueue;
+    readonly now?: () => Date;
+}): A2APushNotificationDeliveryQueueResult;
+export declare function processNextA2APushNotificationDelivery(options: {
+    readonly queue: JsonFileA2APushNotificationDeliveryQueue;
+    readonly transport: A2APushNotificationTransport;
+    readonly attemptStore?: A2APushNotificationAttemptStore;
+    readonly now?: () => Date;
+}): Promise<A2APushNotificationDeliveryWorkerResult>;
+export declare function buildA2APushNotificationDeliveryRequest(config: A2ATaskPushNotificationConfig, task: A2ATask): A2APushNotificationDeliveryRequest;
+export declare function createA2APushHttpTransport(options?: A2APushHttpTransportOptions): A2APushNotificationTransport;