@automate.ax/api-contract 0.76.0 → 0.77.0

package/src/deployment.ts

@@ -1,10 +1,11 @@
 import { oc } from "@orpc/contract"
 import * as z from "zod"
+import { cursorPageOutputSchema, cursorPaginationInputSchema } from "./schemas"
 
 /** SDK compatibility version used to select the immutable runtime image. */
 export const AUTOMATION_SDK_VERSION = "2"
 
-const DEPLOYMENT_STATUS_SCHEMA = z.enum([
+export const deploymentStatusSchema = z.enum([
   "planning",
   "awaiting_authorization",
   "configuring",
@@ -17,7 +18,7 @@ const DEPLOYMENT_STATUS_SCHEMA = z.enum([
 const DEPLOYMENT_IN_PROGRESS_ERROR = {
   data: z.object({
     deploymentId: z.string(),
-    status: DEPLOYMENT_STATUS_SCHEMA,
+    status: deploymentStatusSchema,
   }),
   message: "A deployment is already in progress.",
   status: 409,
@@ -30,8 +31,70 @@ const GIT_SOURCE_SCHEMA = z.object({
   repositoryUrl: z.string().min(1),
 })
 
+const DEPLOYMENT_AUTHORIZATION_SCHEMA = z.object({
+  requirements: z
+    .object({
+      binding: z.string(),
+      satisfied: z.boolean(),
+      serviceId: z.string(),
+    })
+    .array(),
+  url: z.url(),
+})
+
+export const deploymentOutputSchema = z.object({
+  authorization: DEPLOYMENT_AUTHORIZATION_SCHEMA.nullable(),
+  automations: z
+    .object({
+      description: z.string(),
+      id: z.string(),
+      identityKey: z.string(),
+      scopes: z
+        .object({
+          name: z.string().optional(),
+          path: z.number().int().nonnegative().array().min(1),
+          presentation: z.enum(["collapsed", "expanded", "hidden"]),
+        })
+        .array(),
+      subscriptions: z
+        .object({
+          config: z.json(),
+          eventType: z.string(),
+          hookSlot: z.number().int().nonnegative(),
+          scopePath: z.number().int().nonnegative().array().default([]),
+        })
+        .array(),
+    })
+    .array(),
+  createdAt: z.date(),
+  failure: z.object({ message: z.string() }).nullable(),
+  id: z.string(),
+  git: GIT_SOURCE_SCHEMA.nullable(),
+  project: z.object({
+    id: z.string(),
+    name: z.string(),
+    organization: z.object({
+      id: z.string(),
+      name: z.string(),
+    }),
+  }),
+  status: deploymentStatusSchema,
+})
+
 export const deploymentContract = {
-  cancel: oc.input(z.object({ deploymentId: z.string() })).output(z.void()),
+  cancel: oc
+    .route({
+      method: "DELETE",
+      path: "/deployments/{deploymentId}",
+      operationId: "cancelDeployment",
+      summary: "Cancel deployment",
+      description:
+        "Cancels a deployment that is planning, awaiting authorization, or configuring.",
+      successStatus: 204,
+      tags: ["Deployments"],
+    })
+    .input(z.object({ deploymentId: z.string() }))
+    .output(z.void()),
   create: oc
     .errors({ DEPLOYMENT_IN_PROGRESS: DEPLOYMENT_IN_PROGRESS_ERROR })
     .input(
@@ -64,50 +127,62 @@ export const deploymentContract = {
       }),
     )
     .output(z.object({ id: z.string() })),
-  get: oc.input(z.object({ deploymentId: z.string() })).output(
-    z.object({
-      automations: z
-        .object({
-          description: z.string(),
-          id: z.string(),
-          identityKey: z.string(),
-          scopes: z
-            .object({
-              name: z.string().optional(),
-              path: z.number().int().nonnegative().array().min(1),
-              presentation: z.enum(["collapsed", "expanded", "hidden"]),
-            })
-            .array(),
-          subscriptions: z
-            .object({
-              config: z.json(),
-              eventType: z.string(),
-              hookSlot: z.number().int().nonnegative(),
-              scopePath: z.number().int().nonnegative().array().default([]),
-            })
-            .array(),
+  get: oc
+    .route({
+      method: "GET",
+      path: "/deployments/{deploymentId}",
+      operationId: "getDeployment",
+      summary: "Get deployment",
+      description:
+        "Returns normalized deployment status, authorization requirements, and planned automations.",
+      tags: ["Deployments"],
+    })
+    .input(z.object({ deploymentId: z.string() }))
+    .output(deploymentOutputSchema),
+  list: oc
+    .route({
+      method: "GET",
+      path: "/deployments",
+      operationId: "listDeployments",
+      summary: "List deployments",
+      description:
+        "Lists deployments visible to the caller, optionally filtered by organization, project, status, or creation time.",
+      tags: ["Deployments"],
+    })
+    .input(
+      cursorPaginationInputSchema
+        .extend({
+          organizationId: z.string().optional(),
+          projectId: z.string().optional(),
+          since: z.date().optional(),
+          status: deploymentStatusSchema.optional(),
+          until: z.date().optional(),
         })
-        .array(),
-      createdAt: z.date(),
-      id: z.string(),
-      git: GIT_SOURCE_SCHEMA.nullable(),
-      job: z
-        .object({
-          attempts: z.number().int().nonnegative(),
-          error: z.string().nullable(),
-          maxAttempts: z.number().int().positive(),
-          nextRunAt: z.date(),
+        .superRefine(({ since, until }, context) => {
+          if (since !== undefined && until !== undefined && since > until) {
+            context.addIssue({
+              code: "custom",
+              message: "Since must be before or equal to until.",
+              path: ["since"],
+            })
+          }
         })
-        .nullable(),
-      project: z.object({
-        id: z.string(),
-        name: z.string(),
-      }),
-      status: DEPLOYMENT_STATUS_SCHEMA,
-    }),
-  ),
+        .prefault({}),
+    )
+    .output(cursorPageOutputSchema(deploymentOutputSchema)),
   redeploy: oc
     .errors({ DEPLOYMENT_IN_PROGRESS: DEPLOYMENT_IN_PROGRESS_ERROR })
+    .route({
+      method: "POST",
+      path: "/projects/{projectId}/deployments/redeploy",
+      operationId: "redeployProject",
+      summary: "Redeploy project",
+      description:
+        "Creates a deployment from the project's active artifact and plans with explicit integration account bindings.",
+      successStatus: 201,
+      successDescription: "Redeployment created.",
+      tags: ["Deployments"],
+    })
     .input(
       z.object({
         bindings: z

package/src/events/google-meet.ts

@@ -0,0 +1,48 @@
+import { oc } from "@orpc/contract"
+import { z } from "zod"
+
+export const googleMeetEventsContract = {
+  googleMeetPush: oc
+    .route({
+      method: "POST",
+      path: "/events/google-meet",
+      operationId: "receiveGoogleMeetPush",
+      summary: "Receive a Google Meet push notification",
+      description:
+        "Receives and authenticates Google Meet CloudEvents delivered by Google Cloud Pub/Sub.",
+      tags: ["Events"],
+      successStatus: 204,
+    })
+    .input(
+      z.object({
+        /** Pub/Sub message containing one encoded Google Workspace CloudEvent. */
+        message: z.object({
+          /** CloudEvent routing attributes supplied by Pub/Sub. */
+          attributes: z.looseObject({
+            "ce-datacontenttype": z.literal("application/json"),
+            "ce-id": z.string().min(1),
+            "ce-source": z.string().min(1),
+            "ce-specversion": z.literal("1.0"),
+            "ce-subject": z.string().min(1),
+            "ce-time": z.iso.datetime({ offset: true }),
+            "ce-type": z.string().min(1),
+          }),
+
+          /** Base64-encoded CloudEvent data. */
+          data: z.string().min(1),
+
+          /** Pub/Sub message identifier. */
+          messageId: z.string().min(1),
+
+          /** RFC 3339 time at which Pub/Sub published the notification. */
+          publishTime: z.iso.datetime({ offset: true }),
+        }),
+
+        /** Pub/Sub subscription that delivered the message. */
+        subscription: z.literal(
+          "projects/opkitty/subscriptions/automate-ax-google-meet-push",
+        ),
+      }),
+    )
+    .output(z.void()),
+}

package/src/events/index.ts

@@ -3,6 +3,7 @@ import { asanaEventsContract } from "./asana"
 import { brevoEventsContract } from "./brevo"
 import { googleCalendarEventsContract } from "./google-calendar"
 import { googleFormsEventsContract } from "./google-forms"
+import { googleMeetEventsContract } from "./google-meet"
 import { gmailEventsContract } from "./gmail"
 import { githubEventsContract } from "./github"
 import { linearEventsContract } from "./linear"
@@ -20,6 +21,7 @@ export const eventsContract = {
   ...brevoEventsContract,
   ...googleCalendarEventsContract,
   ...googleFormsEventsContract,
+  ...googleMeetEventsContract,
   ...gmailEventsContract,
   ...githubEventsContract,
   ...linearEventsContract,

package/src/execution-data.ts

@@ -0,0 +1,69 @@
+import { oc } from "@orpc/contract"
+import { z } from "zod"
+
+export const EXECUTION_DATASET_VERSION = 4
+
+export const executionDatasetResourceSchema = z.enum([
+  "projects",
+  "automations",
+  "contexts",
+  "context-parents",
+  "event-links",
+  "events",
+  "actions",
+  "signal-invocations",
+  "signal-coordinators",
+  "signal-offers",
+  "signal-decisions",
+  "logs",
+  "outputs",
+  "trace-spans",
+])
+
+export const executionDatasetScopeSchema = z.object({
+  organizationId: z.string().nullable(),
+  projectId: z.string().nullable(),
+  since: z.iso.datetime({ offset: true }).nullable(),
+})
+
+export const executionDatasetManifestSchema = z.object({
+  consistency: z.literal("eventual"),
+  profileId: z.string().min(1),
+  resources: z
+    .object({
+      name: executionDatasetResourceSchema,
+      url: z.url(),
+    })
+    .array(),
+  schemaVersion: z.literal(EXECUTION_DATASET_VERSION),
+  scope: executionDatasetScopeSchema,
+})
+
+export type ExecutionDatasetManifest = z.infer<
+  typeof executionDatasetManifestSchema
+>
+export type ExecutionDatasetResource = z.infer<
+  typeof executionDatasetResourceSchema
+>
+export type ExecutionDatasetScope = z.infer<typeof executionDatasetScopeSchema>
+
+export const executionDataContract = {
+  manifest: oc
+    .route({
+      method: "GET",
+      path: "/execution-data/manifest",
+      operationId: "getExecutionDataManifest",
+      summary: "Get execution data manifest",
+      description:
+        "Returns authenticated Electric shape resources for a validated execution-data scope.",
+      tags: ["Execution data"],
+    })
+    .input(
+      z.object({
+        organizationId: z.string().optional(),
+        projectId: z.string().optional(),
+        since: z.iso.datetime({ offset: true }).optional(),
+      }),
+    )
+    .output(executionDatasetManifestSchema),
+}

package/src/index.ts

@@ -5,21 +5,50 @@ import { authContract } from "./auth"
 import { authorizationContract } from "./authorization"
 import { deploymentContract } from "./deployment"
 import { eventsContract } from "./events"
+import { executionDataContract } from "./execution-data"
 import { orgContract } from "./org"
 import { projectContract } from "./project"
 import { runtimeContract } from "./runtime"
 
-export { automationExecutionStatusSchema } from "./automation"
-export { AUTOMATION_SDK_VERSION } from "./deployment"
+export {
+  automationExecutionStatusSchema,
+  automationOutputSchema,
+} from "./automation"
+export {
+  EXECUTION_DATASET_VERSION,
+  executionDatasetManifestSchema,
+  executionDatasetResourceSchema,
+  executionDatasetScopeSchema,
+  type ExecutionDatasetManifest,
+  type ExecutionDatasetResource,
+  type ExecutionDatasetScope,
+  executionDataContract,
+} from "./execution-data"
+export {
+  AUTOMATION_SDK_VERSION,
+  deploymentOutputSchema,
+  deploymentStatusSchema,
+} from "./deployment"
 export {
   AUTOMATION_ERROR_CAUSE_DEPTH,
   automationErrorSchema,
   type AutomationErrorValue,
 } from "./errors"
-export { integrationAccountOutputSchema } from "./account"
+export {
+  integrationAccountOutputSchema,
+  integrationAccountRevocationImpactOutputSchema,
+  integrationAccountRevocationOutputSchema,
+  integrationServiceOutputSchema,
+} from "./account"
 export {
   AUTOMATION_INVOCATION_DEFAULT_ENTRYPOINT,
   AUTOMATION_INVOCATION_RESERVED_ENTRYPOINT_PREFIX,
+  AUTOMATION_LOG_MAX_ENTRIES,
+  AUTOMATION_LOG_MAX_MESSAGE_LENGTH,
+  AUTOMATION_OBSERVABILITY_MAX_ENCODED_BYTES,
+  AUTOMATION_OBSERVABILITY_MAX_FIELDS,
+  AUTOMATION_TRACE_MAX_NAME_LENGTH,
+  AUTOMATION_TRACE_MAX_SPANS,
   DEFAULT_GATEWAY_MODEL_ID,
   automationInvocationInputSchema,
   automationInvocationOutputSchema,
@@ -50,7 +79,12 @@ export {
   publicOrganizationOutputSchema,
 } from "./org"
 export { projectOutputSchema } from "./project"
-export { reasonableNameSchema } from "./schemas"
+export {
+  cursorPageInfoSchema,
+  cursorPageOutputSchema,
+  cursorPaginationInputSchema,
+  reasonableNameSchema,
+} from "./schemas"
 export { userOutputSchema } from "./auth"
 export {
   managementPermissionStatement,
@@ -61,7 +95,24 @@ export {
 
 /** Procedures exposed by the public Node client and OpenAPI document. */
 export const publicContract = {
+  account: accountContract,
+  automation: {
+    get: automationContract.get,
+    list: automationContract.list,
+    update: automationContract.update,
+  },
   apiKey: apiKeyContract,
+  authorization: {
+    get: authorizationContract.get,
+    proceed: authorizationContract.proceed,
+  },
+  deployment: {
+    cancel: deploymentContract.cancel,
+    get: deploymentContract.get,
+    list: deploymentContract.list,
+    redeploy: deploymentContract.redeploy,
+  },
+  executionData: executionDataContract,
   org: {
     create: orgContract.create,
     delete: orgContract.delete,
@@ -87,12 +138,14 @@ export const publicContract = {
 /** Procedures used by first-party control-plane clients. */
 export const firstPartyContract = {
   ...publicContract,
-  account: accountContract,
-  automation: automationContract,
+  automation: {
+    ...publicContract.automation,
+    getExecution: automationContract.getExecution,
+    listExecutions: automationContract.listExecutions,
+  },
   authorization: {
+    ...publicContract.authorization,
     beginConnection: authorizationContract.beginConnection,
-    get: authorizationContract.get,
-    proceed: authorizationContract.proceed,
     selectAccount: authorizationContract.selectAccount,
     submitCredentials: authorizationContract.submitCredentials,
   },

package/src/org.ts

@@ -1,6 +1,10 @@
 import { oc } from "@orpc/contract"
 import * as z from "zod"
-import { reasonableNameSchema } from "./schemas"
+import {
+  cursorPageOutputSchema,
+  cursorPaginationInputSchema,
+  reasonableNameSchema,
+} from "./schemas"
 
 export const organizationRoleSchema = z.enum(["member", "admin", "owner"])
 
@@ -185,13 +189,13 @@ export const orgContract = {
       tags: ["Organizations"],
     })
     .input(
-      z
-        .object({
+      cursorPaginationInputSchema
+        .extend({
           query: z.string().min(1).optional(),
         })
-        .default({}),
+        .prefault({}),
     )
-    .output(organizationSummaryOutputSchema.array()),
+    .output(cursorPageOutputSchema(organizationSummaryOutputSchema)),
   remove: oc
     .route({
       method: "DELETE",

package/src/project.ts

@@ -1,6 +1,10 @@
 import { oc } from "@orpc/contract"
 import * as z from "zod"
-import { reasonableNameSchema } from "./schemas"
+import {
+  cursorPageOutputSchema,
+  cursorPaginationInputSchema,
+  reasonableNameSchema,
+} from "./schemas"
 
 const TRANSACTION_OUTPUT_SCHEMA = z.object({
   txid: z.number().int().nonnegative(),
@@ -61,14 +65,14 @@ export const projectContract = {
       tags: ["Projects"],
     })
     .input(
-      z
-        .object({
+      cursorPaginationInputSchema
+        .extend({
           organizationId: z.string().optional(),
           query: z.string().min(1).optional(),
         })
-        .optional(),
+        .prefault({}),
     )
-    .output(projectOutputSchema.array()),
+    .output(cursorPageOutputSchema(projectOutputSchema)),
   get: oc
     .route({
       method: "GET",

package/src/runtime.ts

@@ -12,6 +12,12 @@ export const DEFAULT_GATEWAY_MODEL_ID =
   "openai/gpt-4.1-nano" satisfies GatewayModelId
 export const AUTOMATION_INVOCATION_DEFAULT_ENTRYPOINT = "default"
 export const AUTOMATION_INVOCATION_RESERVED_ENTRYPOINT_PREFIX = "__$"
+export const AUTOMATION_LOG_MAX_ENTRIES = 1_000
+export const AUTOMATION_TRACE_MAX_SPANS = 250
+export const AUTOMATION_OBSERVABILITY_MAX_FIELDS = 64
+export const AUTOMATION_OBSERVABILITY_MAX_ENCODED_BYTES = 64 * 1_024
+export const AUTOMATION_LOG_MAX_MESSAGE_LENGTH = 16_384
+export const AUTOMATION_TRACE_MAX_NAME_LENGTH = 256
 
 const OUTCOME_SEQUENCE_SCHEMA = z.number().int().positive()
 const HOOK_SCOPE_PATH_SCHEMA = z
@@ -20,6 +26,23 @@ const HOOK_SCOPE_PATH_SCHEMA = z
   .nonnegative()
   .array()
   .default([])
+const OBSERVABILITY_FIELDS_SCHEMA = z
+  .record(z.string().min(1).max(128), encodableSchema)
+  .refine(
+    (fields) =>
+      Object.keys(fields).length <= AUTOMATION_OBSERVABILITY_MAX_FIELDS,
+    `Observability fields may contain at most ${AUTOMATION_OBSERVABILITY_MAX_FIELDS} entries.`,
+  )
+const LOG_INDEX_SCHEMA = z
+  .number()
+  .int()
+  .min(0)
+  .max(AUTOMATION_LOG_MAX_ENTRIES - 1)
+const TRACE_SPAN_INDEX_SCHEMA = z
+  .number()
+  .int()
+  .min(0)
+  .max(AUTOMATION_TRACE_MAX_SPANS - 1)
 
 const AUTOMATION_INVOCATION_RUN_AT_SCHEMA = z.union([
   z.date(),
@@ -685,6 +708,24 @@ export const runtimeContract = {
       ]),
     )
     .output(z.void()),
+  completeTraceSpan: oc
+    .input(
+      z
+        .object({
+          completedAt: z.date(),
+          spanIndex: TRACE_SPAN_INDEX_SCHEMA,
+        })
+        .and(
+          z.union([
+            z.object({ status: z.literal("succeeded") }),
+            z.object({
+              failure: automationErrorSchema,
+              status: z.literal("failed"),
+            }),
+          ]),
+        ),
+    )
+    .output(z.void()),
   generate: oc
     .input(RUNTIME_GENERATION_INPUT_SCHEMA)
     .output(generationResultSchema),
@@ -715,7 +756,7 @@ export const runtimeContract = {
     )
     .output(
       z.object({
-        connectionId: z.string().min(1),
+        connectionMethodId: z.string().min(1),
         secret: z.record(z.string(), z.unknown()),
         serviceId: z.string(),
       }),
@@ -731,6 +772,29 @@ export const runtimeContract = {
       }),
     )
     .output(z.void()),
+  sendLog: oc
+    .input(
+      z.object({
+        fields: OBSERVABILITY_FIELDS_SCHEMA.optional(),
+        level: z.enum(["debug", "info", "warn", "error"]),
+        logIndex: LOG_INDEX_SCHEMA,
+        message: z.string().min(1).max(AUTOMATION_LOG_MAX_MESSAGE_LENGTH),
+        spanIndex: TRACE_SPAN_INDEX_SCHEMA.optional(),
+        timestamp: z.date(),
+      }),
+    )
+    .output(z.void()),
+  startTraceSpan: oc
+    .input(
+      z.object({
+        attributes: OBSERVABILITY_FIELDS_SCHEMA.optional(),
+        name: z.string().min(1).max(AUTOMATION_TRACE_MAX_NAME_LENGTH),
+        parentSpanIndex: TRACE_SPAN_INDEX_SCHEMA.optional(),
+        spanIndex: TRACE_SPAN_INDEX_SCHEMA,
+        startedAt: z.date(),
+      }),
+    )
+    .output(z.void()),
   sendEmail: oc
     .input(
       z

package/src/schemas.ts

@@ -1,3 +1,25 @@
 import * as z from "zod"
 
+export const cursorPaginationInputSchema = z.object({
+  cursor: z.string().min(1).optional(),
+  limit: z.number().int().min(1).max(100).default(50),
+})
+
+export const cursorPageInfoSchema = z.object({
+  hasMore: z.boolean(),
+  nextCursor: z.string().nullable(),
+})
+
+/**
+ * Builds the common cursor-paginated collection response.
+ *
+ * @param itemSchema - Schema for one collection item.
+ */
+export function cursorPageOutputSchema<T extends z.ZodType>(itemSchema: T) {
+  return z.object({
+    items: itemSchema.array(),
+    pageInfo: cursorPageInfoSchema,
+  })
+}
+
 export const reasonableNameSchema = z.string().min(1).max(255).trim()