@automate.ax/integration-contracts 0.124.0 → 0.126.0

package/src/apify/schemas.ts

@@ -0,0 +1,214 @@
+import * as z from "zod"
+
+export const APIFY_JOB_STATUS_SCHEMA = z.enum([
+  "READY",
+  "RUNNING",
+  "SUCCEEDED",
+  "FAILED",
+  "TIMING-OUT",
+  "TIMED-OUT",
+  "ABORTING",
+  "ABORTED",
+])
+
+const APIFY_DATE_SCHEMA = z.union([z.date(), z.iso.datetime()])
+const APIFY_RUN_META_SCHEMA = z.looseObject({
+  origin: z.string(),
+  scheduleId: z.string().nullable().optional(),
+  scheduledAt: APIFY_DATE_SCHEMA.nullable().optional(),
+})
+const APIFY_RUN_OPTIONS_SCHEMA = z.looseObject({
+  build: z.string(),
+  diskMbytes: z.number().int().nonnegative(),
+  maxItems: z.number().int().nonnegative().nullable().optional(),
+  maxTotalChargeUsd: z.number().nonnegative().nullable().optional(),
+  memoryMbytes: z.number().int().min(128).max(32_768),
+  timeoutSecs: z.number().int().nonnegative(),
+})
+const APIFY_RUN_STATS_SCHEMA = z.looseObject({
+  computeUnits: z.number().nonnegative().optional(),
+  durationMillis: z.number().int().nonnegative().optional(),
+  runTimeSecs: z.number().nonnegative().optional(),
+})
+const APIFY_BUILD_META_SCHEMA = z.looseObject({ origin: z.string() })
+const APIFY_BUILD_OPTIONS_SCHEMA = z.looseObject({
+  betaPackages: z.boolean().optional(),
+  diskMbytes: z.number().int().nonnegative().optional(),
+  memoryMbytes: z.number().int().min(128).max(32_768).optional(),
+  useCache: z.boolean().optional(),
+})
+const APIFY_BUILD_STATS_SCHEMA = z.looseObject({
+  computeUnits: z.number().nonnegative(),
+  durationMillis: z.number().int().nonnegative(),
+  runTimeSecs: z.number().nonnegative(),
+})
+
+const APIFY_RUN_WIRE_SCHEMA = z.looseObject({
+  actId: z.string(),
+  actorTaskId: z.string().nullable().optional(),
+  buildId: z.string(),
+  buildNumber: z.string().nullable().optional(),
+  defaultDatasetId: z.string(),
+  defaultKeyValueStoreId: z.string(),
+  defaultRequestQueueId: z.string(),
+  exitCode: z.number().int().nullable().optional(),
+  finishedAt: APIFY_DATE_SCHEMA.nullable().optional(),
+  id: z.string(),
+  meta: APIFY_RUN_META_SCHEMA,
+  options: APIFY_RUN_OPTIONS_SCHEMA.optional(),
+  startedAt: APIFY_DATE_SCHEMA,
+  stats: APIFY_RUN_STATS_SCHEMA.optional(),
+  status: APIFY_JOB_STATUS_SCHEMA,
+  statusMessage: z.string().nullable().optional(),
+  usageTotalUsd: z.number().nonnegative().nullable().optional(),
+  userId: z.string().optional(),
+})
+
+const APIFY_BUILD_WIRE_SCHEMA = z.looseObject({
+  actId: z.string(),
+  buildNumber: z.string(),
+  finishedAt: APIFY_DATE_SCHEMA.nullable().optional(),
+  id: z.string(),
+  meta: APIFY_BUILD_META_SCHEMA.optional(),
+  options: APIFY_BUILD_OPTIONS_SCHEMA.nullable().optional(),
+  startedAt: APIFY_DATE_SCHEMA,
+  stats: APIFY_BUILD_STATS_SCHEMA.nullable().optional(),
+  status: APIFY_JOB_STATUS_SCHEMA,
+  usageTotalUsd: z.number().nonnegative().nullable().optional(),
+  userId: z.string().optional(),
+})
+
+export const APIFY_RUN_SCHEMA = z.object({
+  actorId: z.string(),
+  actorTaskId: z.string().nullable().optional(),
+  buildId: z.string(),
+  buildNumber: z.string().nullable().optional(),
+  defaultDatasetId: z.string(),
+  defaultKeyValueStoreId: z.string(),
+  defaultRequestQueueId: z.string(),
+  exitCode: z.number().int().nullable().optional(),
+  finishedAt: z.iso.datetime().nullable().optional(),
+  id: z.string(),
+  meta: z.object({
+    origin: z.string(),
+    scheduleId: z.string().nullable().optional(),
+    scheduledAt: z.iso.datetime().nullable().optional(),
+  }),
+  options: z
+    .object({
+      build: z.string(),
+      diskMbytes: z.number().int().nonnegative(),
+      maxItems: z.number().int().nonnegative().nullable().optional(),
+      maxTotalChargeUsd: z.number().nonnegative().nullable().optional(),
+      memoryMbytes: z.number().int().min(128).max(32_768),
+      timeoutSecs: z.number().int().nonnegative(),
+    })
+    .optional(),
+  startedAt: z.iso.datetime(),
+  stats: z
+    .object({
+      computeUnits: z.number().nonnegative().optional(),
+      durationMillis: z.number().int().nonnegative().optional(),
+      runTimeSecs: z.number().nonnegative().optional(),
+    })
+    .optional(),
+  status: APIFY_JOB_STATUS_SCHEMA,
+  statusMessage: z.string().nullable().optional(),
+  usageTotalUsd: z.number().nonnegative().nullable().optional(),
+  userId: z.string().optional(),
+})
+
+export const APIFY_BUILD_SCHEMA = z.object({
+  actorId: z.string(),
+  buildNumber: z.string(),
+  finishedAt: z.iso.datetime().nullable().optional(),
+  id: z.string(),
+  meta: z.object({ origin: z.string() }).optional(),
+  options: z
+    .object({
+      betaPackages: z.boolean().optional(),
+      diskMbytes: z.number().int().nonnegative().optional(),
+      memoryMbytes: z.number().int().min(128).max(32_768).optional(),
+      useCache: z.boolean().optional(),
+    })
+    .nullable()
+    .optional(),
+  startedAt: z.iso.datetime(),
+  stats: z
+    .object({
+      computeUnits: z.number().nonnegative(),
+      durationMillis: z.number().int().nonnegative(),
+      runTimeSecs: z.number().nonnegative(),
+    })
+    .nullable()
+    .optional(),
+  status: APIFY_JOB_STATUS_SCHEMA,
+  usageTotalUsd: z.number().nonnegative().nullable().optional(),
+  userId: z.string().optional(),
+})
+
+/**
+ * Converts an official Apify Actor run into the public camelCase contract.
+ *
+ * @param value - Official client or webhook run value.
+ */
+export function mapApifyRun(value: unknown): z.output<typeof APIFY_RUN_SCHEMA> {
+  const run = APIFY_RUN_WIRE_SCHEMA.parse(value)
+  return APIFY_RUN_SCHEMA.parse({
+    actorId: run.actId,
+    actorTaskId: run.actorTaskId,
+    buildId: run.buildId,
+    buildNumber: run.buildNumber,
+    defaultDatasetId: run.defaultDatasetId,
+    defaultKeyValueStoreId: run.defaultKeyValueStoreId,
+    defaultRequestQueueId: run.defaultRequestQueueId,
+    exitCode: run.exitCode,
+    finishedAt: toIsoDate(run.finishedAt),
+    id: run.id,
+    meta: {
+      origin: run.meta.origin,
+      scheduleId: run.meta.scheduleId,
+      scheduledAt: toIsoDate(run.meta.scheduledAt),
+    },
+    options: run.options,
+    startedAt: toIsoDate(run.startedAt),
+    stats: run.stats,
+    status: run.status,
+    statusMessage: run.statusMessage,
+    usageTotalUsd: run.usageTotalUsd,
+    userId: run.userId,
+  })
+}
+
+/**
+ * Converts an official Apify Actor build into the public camelCase contract.
+ *
+ * @param value - Official client or webhook build value.
+ */
+export function mapApifyBuild(
+  value: unknown,
+): z.output<typeof APIFY_BUILD_SCHEMA> {
+  const build = APIFY_BUILD_WIRE_SCHEMA.parse(value)
+  return APIFY_BUILD_SCHEMA.parse({
+    actorId: build.actId,
+    buildNumber: build.buildNumber,
+    finishedAt: toIsoDate(build.finishedAt),
+    id: build.id,
+    meta: build.meta,
+    options: build.options,
+    startedAt: toIsoDate(build.startedAt),
+    stats: build.stats,
+    status: build.status,
+    usageTotalUsd: build.usageTotalUsd,
+    userId: build.userId,
+  })
+}
+
+/**
+ * Normalizes an optional provider date without changing nullability.
+ *
+ * @param value - Provider date value.
+ */
+function toIsoDate(value: Date | string | null | undefined) {
+  return value instanceof Date ? value.toISOString() : value
+}

package/src/reddit/api.ts

@@ -0,0 +1,183 @@
+import * as z from "zod"
+
+const REDDIT_API_ORIGIN = "https://oauth.reddit.com/"
+const REDDIT_API_URL = new URL(REDDIT_API_ORIGIN)
+
+export const REDDIT_OAUTH_SECRET_SCHEMA = z.object({
+  accessToken: z.string().min(1),
+  expiresAt: z.number().int().positive(),
+  refreshToken: z.string().min(1),
+  tokenType: z.string().min(1),
+  userAgent: z.string().min(1),
+})
+
+const REDDIT_API_ERROR_SCHEMA = z.looseObject({
+  error: z.number().int().optional(),
+  message: z.string().optional(),
+  reason: z.string().optional(),
+})
+export const REDDIT_ERROR_TUPLE_SCHEMA = z.tuple([
+  z.string(),
+  z.string(),
+  z.string().nullable(),
+])
+const REDDIT_JSON_ERRORS_SCHEMA = z.looseObject({
+  json: z.object({
+    errors: REDDIT_ERROR_TUPLE_SCHEMA.array(),
+  }),
+})
+export const REDDIT_JSON_STATUS_SCHEMA = z.object({
+  json: z.object({ errors: REDDIT_ERROR_TUPLE_SCHEMA.array() }),
+})
+
+export interface RedditRequestOptions<TSchema extends z.ZodType> {
+  body?: Record<string, boolean | number | string | undefined>
+  method?: "DELETE" | "GET" | "POST" | "PUT"
+  query?: Record<
+    string,
+    boolean | number | string | readonly string[] | null | undefined
+  >
+  responseSchema: TSchema
+}
+
+/** Error returned by a rejected Reddit Data API request. */
+export class RedditApiError extends Error {
+  readonly details:
+    | { error?: number; message?: string; reason?: string }
+    | { errors: [string, string, null | string][] }
+    | { response: string }
+  readonly retryAfter?: string
+  readonly status: number
+
+  /**
+   * Creates an error from a rejected Reddit response.
+   *
+   * @param status - HTTP response status.
+   * @param details - Parsed Reddit failure details.
+   * @param retryAfter - Provider retry delay in seconds, when present.
+   */
+  constructor(
+    status: number,
+    details: RedditApiError["details"],
+    retryAfter?: string,
+  ) {
+    const jsonError = "errors" in details ? details.errors[0]?.[1] : undefined
+    super(
+      ("message" in details
+        ? (details.message ?? details.reason)
+        : undefined) ??
+        jsonError ??
+        `Reddit API request failed (${status}).`,
+    )
+    this.name = "RedditApiError"
+    this.details = details
+    this.retryAfter = retryAfter
+    this.status = status
+  }
+}
+
+/**
+ * Creates an authenticated Reddit Data API client.
+ *
+ * @param secret - Stored Reddit OAuth credentials and registered User-Agent.
+ */
+export function getRedditApi(secret: unknown) {
+  const credentials = REDDIT_OAUTH_SECRET_SCHEMA.parse(secret)
+
+  return {
+    /**
+     * Sends one request below Reddit's OAuth API origin.
+     *
+     * @param path - Relative Reddit API path.
+     * @param options - Request method, parameters, and response contract.
+     */
+    async request<TSchema extends z.ZodType>(
+      path: string,
+      options: RedditRequestOptions<TSchema>,
+    ): Promise<z.output<TSchema>> {
+      const normalizedPath = path.replace(/^\/+/, "")
+      if (
+        !normalizedPath ||
+        normalizedPath.includes("://") ||
+        normalizedPath.includes("\\")
+      ) {
+        throw new TypeError("Reddit API paths must be relative.")
+      }
+
+      const url = new URL(normalizedPath, REDDIT_API_ORIGIN)
+      if (url.origin !== REDDIT_API_URL.origin) {
+        throw new TypeError("Reddit API paths must remain on oauth.reddit.com.")
+      }
+      url.searchParams.set("raw_json", "1")
+      for (const [key, value] of Object.entries(options.query ?? {})) {
+        if (value == null) continue
+        url.searchParams.set(
+          key,
+          Array.isArray(value) ? value.join(",") : String(value),
+        )
+      }
+
+      const headers = new Headers({
+        Accept: "application/json",
+        Authorization: `${credentials.tokenType} ${credentials.accessToken}`,
+        "User-Agent": credentials.userAgent,
+      })
+      const body = options.body
+        ? new URLSearchParams(
+            Object.entries(options.body).flatMap(([key, value]) =>
+              value === undefined
+                ? []
+                : ([[key, String(value)]] satisfies [string, string][]),
+            ),
+          )
+        : undefined
+      if (body) {
+        headers.set("Content-Type", "application/x-www-form-urlencoded")
+      }
+
+      const response = await fetch(url, {
+        body,
+        headers,
+        method: options.method ?? "GET",
+      })
+      const text = await response.text()
+      const parsed = parseJson(text)
+      const jsonErrors = REDDIT_JSON_ERRORS_SCHEMA.safeParse(parsed)
+      const retryAfter =
+        response.headers.get("Retry-After") ??
+        response.headers.get("X-Ratelimit-Reset") ??
+        undefined
+      if (jsonErrors.success && jsonErrors.data.json.errors.length > 0) {
+        throw new RedditApiError(
+          response.ok ? 400 : response.status,
+          { errors: jsonErrors.data.json.errors },
+          retryAfter,
+        )
+      }
+      if (!response.ok) {
+        const error = REDDIT_API_ERROR_SCHEMA.safeParse(parsed)
+        throw new RedditApiError(
+          response.status,
+          error.success ? error.data : { response: text },
+          retryAfter,
+        )
+      }
+      const result = options.responseSchema.safeParse(parsed)
+      if (!result.success) {
+        throw new RedditApiError(response.status, { response: text })
+      }
+      return result.data
+    },
+  }
+}
+
+/** Parses a provider body while preserving non-JSON failure text. */
+/** @param value - Raw provider response body. */
+function parseJson(value: string): unknown {
+  if (!value) return undefined
+  try {
+    return JSON.parse(value)
+  } catch {
+    return value
+  }
+}

package/src/reddit/events.ts

@@ -0,0 +1,68 @@
+import * as z from "zod"
+import {
+  REDDIT_COMMENT_SCHEMA,
+  REDDIT_MESSAGE_SCHEMA,
+  REDDIT_POST_SCHEMA,
+  REDDIT_SUBREDDIT_NAME_SCHEMA,
+} from "./schemas"
+
+export const REDDIT_SUBREDDIT_TRIGGER_CONFIG_SCHEMA = z.object({
+  subreddit: REDDIT_SUBREDDIT_NAME_SCHEMA,
+})
+export const REDDIT_ACCOUNT_TRIGGER_CONFIG_SCHEMA = z.object({})
+
+export const REDDIT_SUBREDDIT_EVENT_SCHEMA = z.discriminatedUnion("action", [
+  z.object({
+    action: z.literal("commentCreated"),
+    comment: REDDIT_COMMENT_SCHEMA,
+  }),
+  z.object({ action: z.literal("postCreated"), post: REDDIT_POST_SCHEMA }),
+])
+export const REDDIT_INBOX_EVENT_SCHEMA = z.object({
+  action: z.literal("inboxItemCreated"),
+  message: REDDIT_MESSAGE_SCHEMA,
+})
+export const REDDIT_MOD_QUEUE_EVENT_SCHEMA = z.discriminatedUnion("kind", [
+  z.object({ comment: REDDIT_COMMENT_SCHEMA, kind: z.literal("comment") }),
+  z.object({ kind: z.literal("post"), post: REDDIT_POST_SCHEMA }),
+])
+
+export const redditTriggerContracts = {
+  "reddit.inbox.item.received": {
+    configSchema: REDDIT_ACCOUNT_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: REDDIT_INBOX_EVENT_SCHEMA,
+  },
+  "reddit.modQueue.item.received": {
+    configSchema: REDDIT_SUBREDDIT_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: REDDIT_MOD_QUEUE_EVENT_SCHEMA,
+  },
+  "reddit.subreddit.comment.created": {
+    configSchema: REDDIT_SUBREDDIT_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: REDDIT_SUBREDDIT_EVENT_SCHEMA.and(
+      z.object({ action: z.literal("commentCreated") }),
+    ),
+  },
+  "reddit.subreddit.event": {
+    configSchema: REDDIT_SUBREDDIT_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: REDDIT_SUBREDDIT_EVENT_SCHEMA,
+  },
+  "reddit.subreddit.post.created": {
+    configSchema: REDDIT_SUBREDDIT_TRIGGER_CONFIG_SCHEMA,
+    eventSchema: REDDIT_SUBREDDIT_EVENT_SCHEMA.and(
+      z.object({ action: z.literal("postCreated") }),
+    ),
+  },
+} as const
+
+/** Returns broad and semantic event types for one subreddit observation. */
+/** @param event - Normalized post or comment event. */
+export function getRedditSubredditEventTypes(
+  event: z.output<typeof REDDIT_SUBREDDIT_EVENT_SCHEMA>,
+) {
+  return [
+    event.action === "postCreated"
+      ? ("reddit.subreddit.post.created" as const)
+      : ("reddit.subreddit.comment.created" as const),
+    "reddit.subreddit.event" as const,
+  ]
+}

package/src/reddit/index.ts

@@ -0,0 +1,3 @@
+export * from "./api"
+export * from "./events"
+export * from "./schemas"