@automate.ax/api-contract 0.7.0 → 0.8.0

package/dist/index.js

@@ -7,19 +7,67 @@ import { orgContract } from "./org.js";
 import { projectContract } from "./project.js";
 import { runtimeContract } from "./runtime.js";
 export { AUTOMATION_SDK_VERSION, deploymentTriggerInfoSchema, } from "./deployment.js";
+export { runtimeContract } from "./runtime.js";
 export { createdOrganizationApiKeyOutputSchema, organizationApiKeyOutputSchema, } from "./api-key.js";
 export { integrationServiceManifestSchema, } from "./authorization.js";
 export { activeSubscriptionOutputSchema, createdInvitationOutputSchema, organizationDetailsOutputSchema, organizationInvitationOutputSchema, organizationMemberOutputSchema, organizationProjectOutputSchema, organizationRoleSchema, organizationSummaryOutputSchema, publicOrganizationOutputSchema, } from "./org.js";
 export { projectOutputSchema, projectWithOrganizationOutputSchema, } from "./project.js";
 export { reasonableNameSchema } from "./schemas.js";
 export { userOutputSchema } from "./auth.js";
-export const contract = {
+/** Procedures exposed by the public Node client and OpenAPI document. */
+export const publicContract = {
     apiKey: apiKeyContract,
-    authorization: authorizationContract,
+    org: {
+        create: orgContract.create,
+        delete: orgContract.delete,
+        get: orgContract.get,
+        invite: orgContract.invite,
+        leave: orgContract.leave,
+        list: orgContract.list,
+        remove: orgContract.remove,
+        update: orgContract.update,
+    },
+    project: {
+        create: projectContract.create,
+        delete: projectContract.delete,
+        get: projectContract.get,
+        list: projectContract.list,
+        update: projectContract.update,
+    },
+    session: {
+        me: authContract.me,
+    },
+};
+/** Procedures used by first-party control-plane clients. */
+export const firstPartyContract = {
+    ...publicContract,
+    authorization: {
+        beginConnection: authorizationContract.beginConnection,
+        get: authorizationContract.get,
+        selectAccount: authorizationContract.selectAccount,
+        submitCredentials: authorizationContract.submitCredentials,
+    },
     deployment: deploymentContract,
+    org: {
+        ...publicContract.org,
+        canInvite: orgContract.canInvite,
+    },
+    project: {
+        ...publicContract.project,
+        canCreate: projectContract.canCreate,
+    },
+    session: {
+        ...publicContract.session,
+        linkDeviceSession: authContract.linkDeviceSession,
+    },
+};
+/** Complete contract implemented by the API service. */
+export const contract = {
+    ...firstPartyContract,
+    authorization: {
+        ...firstPartyContract.authorization,
+        callback: authorizationContract.callback,
+    },
     events: eventsContract,
-    org: orgContract,
-    project: projectContract,
     runtime: runtimeContract,
-    session: authContract,
 };

package/dist/runtime.d.ts

@@ -64,7 +64,7 @@ export declare const runtimeContract: {
     sendEmail: import("@orpc/contract").ContractProcedureBuilderWithInputOutput<z.ZodObject<{
         subject: z.ZodString;
         text: z.ZodString;
-        to: z.ZodEmail;
+        to: z.ZodUnion<readonly [z.ZodEmail, z.ZodLiteral<"*">]>;
     }, z.core.$strip>, z.ZodObject<{
         id: z.ZodNullable<z.ZodString>;
     }, z.core.$strip>, Record<never, never>, Record<never, never>>;

package/dist/runtime.js

@@ -86,7 +86,7 @@ export const runtimeContract = {
         .input(z.object({
         subject: z.string().min(1),
         text: z.string().min(1),
-        to: z.email(),
+        to: z.union([z.email(), z.literal("*")]),
     }))
         .output(z.object({
         id: z.string().nullable(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automate.ax/api-contract",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Public oRPC contract for the Automate.ax API.",
   "license": "MIT",
   "repository": {
@@ -20,10 +20,13 @@
     "exports": {
       ".": "./src/index.ts"
     },
-    "cjs": false
+    "cjs": false,
+    "conditions": {
+      "bun": "src"
+    }
   },
   "dependencies": {
-    "@automate.ax/codec": "0.7.0",
+    "@automate.ax/codec": "0.8.0",
     "@orpc/contract": "1.13.14",
     "zod": "^4.3.6"
   },
@@ -48,6 +51,7 @@
   },
   "files": [
     "dist",
+    "src",
     "README.md",
     "LICENSE"
   ],
@@ -59,6 +63,7 @@
   },
   "exports": {
     ".": {
+      "bun": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     }

package/src/api-key.ts

@@ -0,0 +1,84 @@
+import { oc } from "@orpc/contract"
+import { z } from "zod"
+import { reasonableNameSchema } from "./schemas"
+
+export const organizationApiKeyOutputSchema = z.object({
+  id: z.string(),
+  name: z.string().nullable(),
+  start: z.string().nullable(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+  expiresAt: z.date().nullable(),
+})
+
+export const createdOrganizationApiKeyOutputSchema =
+  organizationApiKeyOutputSchema.extend({
+    key: z.string(),
+  })
+
+export const apiKeyContract = {
+  create: oc
+    .route({
+      method: "POST",
+      path: "/organizations/{organizationId}/api-keys",
+      operationId: "createOrganizationApiKey",
+      summary: "Create organization API key",
+      description:
+        "Creates an API key owned by the organization. The secret is returned once.",
+      successStatus: 201,
+      successDescription: "API key created.",
+      tags: ["API Keys"],
+    })
+    .input(
+      z.object({
+        organizationId: z.string(),
+        name: reasonableNameSchema,
+      }),
+    )
+    .output(createdOrganizationApiKeyOutputSchema),
+  delete: oc
+    .route({
+      method: "DELETE",
+      path: "/organizations/{organizationId}/api-keys/{keyId}",
+      operationId: "deleteOrganizationApiKey",
+      summary: "Delete organization API key",
+      description: "Permanently revokes an organization API key.",
+      successStatus: 204,
+      tags: ["API Keys"],
+    })
+    .input(
+      z.object({
+        keyId: z.string(),
+        organizationId: z.string(),
+      }),
+    )
+    .output(z.void()),
+  list: oc
+    .route({
+      method: "GET",
+      path: "/organizations/{organizationId}/api-keys",
+      operationId: "listOrganizationApiKeys",
+      summary: "List organization API keys",
+      description: "Lists API keys owned by an organization.",
+      tags: ["API Keys"],
+    })
+    .input(z.object({ organizationId: z.string() }))
+    .output(organizationApiKeyOutputSchema.array()),
+  update: oc
+    .route({
+      method: "PATCH",
+      path: "/organizations/{organizationId}/api-keys/{keyId}",
+      operationId: "updateOrganizationApiKey",
+      summary: "Update organization API key",
+      description: "Updates an organization API key's display name.",
+      tags: ["API Keys"],
+    })
+    .input(
+      z.object({
+        keyId: z.string(),
+        name: reasonableNameSchema,
+        organizationId: z.string(),
+      }),
+    )
+    .output(organizationApiKeyOutputSchema),
+}

package/src/auth.ts

@@ -0,0 +1,39 @@
+import { oc } from "@orpc/contract"
+import { z } from "zod"
+
+export const userOutputSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.email(),
+  emailVerified: z.boolean(),
+  image: z.string().nullable().optional(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+})
+
+export const authContract = {
+  me: oc
+    .route({
+      method: "GET",
+      path: "/me",
+      operationId: "getCurrentUser",
+      summary: "Get current user",
+      description:
+        "Returns the authenticated user for the current bearer token or cookie session.",
+      tags: ["Session"],
+    })
+    .output(userOutputSchema),
+  linkDeviceSession: oc
+    .route({
+      method: "POST",
+      path: "/me/session/link-device",
+      operationId: "linkDeviceSession",
+      summary: "Link device session",
+      description:
+        "Migrates anonymous-session data into authenticated user context.",
+      tags: ["Session"],
+      successStatus: 204,
+    })
+    .input(z.object({ newAccessToken: z.string() }))
+    .output(z.void()),
+}

package/src/authorization.ts

@@ -0,0 +1,151 @@
+import { oc } from "@orpc/contract"
+import { z } from "zod"
+
+const integrationFormFieldBaseSchema = z.object({
+  description: z.string().optional(),
+  label: z.string().min(1),
+  name: z.string().min(1),
+  required: z.boolean(),
+})
+
+const INTEGRATION_FORM_FIELD_SCHEMA = z.discriminatedUnion("input", [
+  integrationFormFieldBaseSchema.extend({
+    default: z.string().optional(),
+    input: z.enum(["email", "text", "url"]),
+    placeholder: z.string().optional(),
+  }),
+  integrationFormFieldBaseSchema.extend({
+    input: z.literal("password"),
+    placeholder: z.string().optional(),
+  }),
+  integrationFormFieldBaseSchema.extend({
+    default: z.number().optional(),
+    input: z.literal("number"),
+    placeholder: z.string().optional(),
+  }),
+  integrationFormFieldBaseSchema.extend({
+    default: z.boolean().optional(),
+    input: z.literal("boolean"),
+  }),
+])
+
+export const integrationServiceManifestSchema = z.object({
+  connection: z.discriminatedUnion("type", [
+    z.object({
+      type: z.literal("redirect"),
+    }),
+    z.object({
+      fields: INTEGRATION_FORM_FIELD_SCHEMA.array().min(1),
+      type: z.literal("form"),
+    }),
+  ]),
+  description: z.string().optional(),
+  name: z.string().min(1),
+})
+
+export type IntegrationServiceManifest = z.infer<
+  typeof integrationServiceManifestSchema
+>
+
+type ScopeRequirement =
+  | string
+  | {
+      requirements: ScopeRequirement[]
+      type: "and" | "or"
+    }
+const SCOPE_REQUIREMENT_SCHEMA: z.ZodType<ScopeRequirement> = z.lazy(() =>
+  z.union([
+    z.string(),
+    z.strictObject({
+      requirements: SCOPE_REQUIREMENT_SCHEMA.array(),
+      type: z.enum(["and", "or"]),
+    }),
+  ]),
+)
+
+export const authorizationContract = {
+  beginConnection: oc
+    .input(
+      z.object({
+        binding: z.string().min(1),
+        deploymentId: z.string(),
+        serviceId: z.string().min(1),
+      }),
+    )
+    .output(z.object({ url: z.url() })),
+  callback: oc
+    .route({
+      method: "GET",
+      path: "/integrations/{serviceId}/callback",
+      operationId: "completeIntegrationAuthorization",
+      summary: "Complete integration authorization",
+      description: "Completes a redirect-based integration authorization flow.",
+      tags: ["Integrations"],
+    })
+    .input(z.object({ serviceId: z.string().min(1) }))
+    .output(z.string()),
+  get: oc
+    .input(
+      z.object({
+        deploymentId: z.string(),
+      }),
+    )
+    .output(
+      z.object({
+        accounts: z
+          .object({
+            checkedAt: z.date().nullable(),
+            error: z
+              .object({
+                code: z.string(),
+                message: z.string(),
+              })
+              .nullable(),
+            id: z.string(),
+            label: z.string(),
+            scopes: z.string().array(),
+            serviceId: z.string(),
+            serviceSub: z.string(),
+          })
+          .array(),
+        requirements: z
+          .object({
+            accountId: z.string().nullable(),
+            binding: z.string(),
+            eligibleAccountIds: z.string().array(),
+            minimalScopes: z.string().array(),
+            requiredScopes: SCOPE_REQUIREMENT_SCHEMA.array(),
+            satisfied: z.boolean(),
+            serviceId: z.string(),
+          })
+          .array(),
+        services: integrationServiceManifestSchema
+          .extend({
+            id: z.string().min(1),
+          })
+          .array(),
+      }),
+    ),
+  submitCredentials: oc
+    .input(
+      z.object({
+        binding: z.string().min(1),
+        data: z.record(
+          z.string(),
+          z.union([z.string(), z.number(), z.boolean()]),
+        ),
+        deploymentId: z.string(),
+        serviceId: z.string().min(1),
+      }),
+    )
+    .output(z.void()),
+  selectAccount: oc
+    .input(
+      z.object({
+        accountId: z.string(),
+        binding: z.string().min(1),
+        deploymentId: z.string(),
+      }),
+    )
+    .output(z.void()),
+}

package/src/deployment.ts

@@ -0,0 +1,107 @@
+import { oc } from "@orpc/contract"
+import { z } from "zod"
+
+/** SDK compatibility version used to select the immutable runtime image. */
+export const AUTOMATION_SDK_VERSION = "1"
+
+export const deploymentTriggerInfoSchema = z.object({
+  details: z
+    .object({
+      label: z.string(),
+      value: z.string(),
+    })
+    .array(),
+  name: z.string(),
+  type: z.string(),
+})
+
+export type DeploymentTriggerInfo = z.infer<typeof deploymentTriggerInfoSchema>
+
+export const deploymentContract = {
+  create: oc
+    .input(
+      z.object({
+        artifact: z.instanceof(Blob),
+        manifest: z
+          .object({
+            entrypoint: z.string().min(1),
+            identityKey: z.string().min(1),
+          })
+          .array()
+          .min(1, "Deployment must include at least one automation.")
+          .superRefine((manifest, context) => {
+            const identityKeys = new Set<string>()
+
+            for (const [index, entry] of manifest.entries()) {
+              if (identityKeys.has(entry.identityKey)) {
+                context.addIssue({
+                  code: "custom",
+                  message: "Automation identity keys must be unique.",
+                  path: [index, "identityKey"],
+                })
+              }
+              identityKeys.add(entry.identityKey)
+
+              if (
+                entry.entrypoint.includes("\\") ||
+                entry.entrypoint.startsWith("/") ||
+                entry.entrypoint
+                  .split("/")
+                  .some(
+                    (segment) =>
+                      segment === "" || segment === "." || segment === "..",
+                  )
+              ) {
+                context.addIssue({
+                  code: "custom",
+                  message: "Entrypoint must be a safe relative POSIX path.",
+                  path: [index, "entrypoint"],
+                })
+              }
+            }
+          }),
+        mode: z.enum(["reconcile", "upsert"]),
+        projectId: z.string(),
+      }),
+    )
+    .output(z.object({ id: z.string() })),
+  get: oc
+    .input(
+      z.object({
+        deploymentId: z.string(),
+        projectId: z.string(),
+      }),
+    )
+    .output(
+      z.object({
+        automations: z
+          .object({
+            description: z.string(),
+            identityKey: z.string(),
+            triggers: deploymentTriggerInfoSchema.array(),
+          })
+          .array(),
+        id: z.string(),
+        job: z
+          .object({
+            attempts: z.number().int().nonnegative(),
+            error: z.string().nullable(),
+            maxAttempts: z.number().int().positive(),
+            nextRunAt: z.date(),
+          })
+          .nullable(),
+        project: z.object({
+          id: z.string(),
+          name: z.string(),
+        }),
+        status: z.enum([
+          "planning",
+          "awaiting_authorization",
+          "configuring",
+          "publishing",
+          "succeeded",
+          "failed",
+        ]),
+      }),
+    ),
+}

package/src/events/gmail.ts

@@ -0,0 +1,34 @@
+import { oc } from "@orpc/contract"
+import { z } from "zod"
+
+export const gmailEventsContract = {
+  gmailPush: oc
+    .route({
+      method: "POST",
+      path: "/events/gmail",
+      operationId: "receiveGmailPush",
+      summary: "Receive a Gmail push notification",
+      description:
+        "Receives and authenticates Gmail mailbox notifications delivered by Google Cloud Pub/Sub.",
+      tags: ["Events"],
+      successStatus: 204,
+    })
+    .input(
+      z.object({
+        /** Pub/Sub message containing the encoded Gmail notification. */
+        message: z.object({
+          /** Base64-encoded Gmail mailbox notification. */
+          data: z.string().min(1),
+
+          /** Provider-assigned identifier used to deduplicate delivery. */
+          messageId: z.string().min(1),
+        }),
+
+        /** Pub/Sub subscription that delivered the message. */
+        subscription: z.literal(
+          "projects/opkitty/subscriptions/automate-ax-gmail-push",
+        ),
+      }),
+    )
+    .output(z.void()),
+}

package/src/events/google-calendar.ts

@@ -0,0 +1,18 @@
+import { oc } from "@orpc/contract"
+import { z } from "zod"
+
+export const googleCalendarEventsContract = {
+  googleCalendarPush: oc
+    .route({
+      method: "POST",
+      path: "/events/google-calendar",
+      operationId: "receiveGoogleCalendarPush",
+      summary: "Receive a Google Calendar push notification",
+      description:
+        "Receives header-only Google Calendar resource-change notifications.",
+      tags: ["Events"],
+      successStatus: 204,
+    })
+    .input(z.void())
+    .output(z.void()),
+}

package/src/events/google-forms.ts

@@ -0,0 +1,41 @@
+import { oc } from "@orpc/contract"
+import { z } from "zod"
+
+export const googleFormsEventsContract = {
+  googleFormsPush: oc
+    .route({
+      method: "POST",
+      path: "/events/google-forms",
+      operationId: "receiveGoogleFormsPush",
+      summary: "Receive a Google Forms push notification",
+      description:
+        "Receives and authenticates Google Forms notifications delivered by Google Cloud Pub/Sub.",
+      tags: ["Events"],
+      successStatus: 204,
+    })
+    .input(
+      z.object({
+        /** Pub/Sub message containing Google Forms notification attributes. */
+        message: z.object({
+          /** Provider routing fields for the watched form. */
+          attributes: z.object({
+            eventType: z.enum(["SCHEMA", "RESPONSES"]),
+            formId: z.string().min(1),
+            watchId: z.string().min(1),
+          }),
+
+          /** Provider-assigned identifier used to deduplicate delivery. */
+          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-forms-push",
+        ),
+      }),
+    )
+    .output(z.void()),
+}

package/src/events/index.ts

@@ -0,0 +1,9 @@
+import { googleCalendarEventsContract } from "./google-calendar"
+import { googleFormsEventsContract } from "./google-forms"
+import { gmailEventsContract } from "./gmail"
+
+export const eventsContract = {
+  ...googleCalendarEventsContract,
+  ...googleFormsEventsContract,
+  ...gmailEventsContract,
+}