@automate.ax/integration-contracts 0.125.0 → 0.126.0

package/dist/reddit/schemas.js

@@ -0,0 +1,398 @@
+import * as z from "zod";
+const REDDIT_ORIGIN = "https://www.reddit.com";
+const REDDIT_EDITED_SCHEMA = z.union([z.literal(false), z.number()]);
+export const REDDIT_THING_ID_SCHEMA = z
+    .string()
+    .regex(/^t[1345]_[a-z0-9]+$/i, "Expected a Reddit thing fullname.");
+export const REDDIT_POST_ID_SCHEMA = z
+    .string()
+    .regex(/^t3_[a-z0-9]+$/i, "Expected a Reddit post fullname.");
+export const REDDIT_CONTENT_ID_SCHEMA = z
+    .string()
+    .regex(/^t[13]_[a-z0-9]+$/i, "Expected a Reddit post or comment fullname.");
+export const REDDIT_INBOX_ID_SCHEMA = z
+    .string()
+    .regex(/^t[14]_[a-z0-9]+$/i, "Expected a Reddit inbox item fullname.");
+export const REDDIT_SUBREDDIT_NAME_SCHEMA = z
+    .string()
+    .trim()
+    .regex(/^[A-Za-z0-9_]{2,21}$/, "Expected a Reddit subreddit name.");
+export const REDDIT_USERNAME_SCHEMA = z
+    .string()
+    .trim()
+    .regex(/^[A-Za-z0-9_-]{3,20}$/, "Expected a Reddit username.");
+export const REDDIT_FLAIR_SCHEMA = z.object({
+    backgroundColor: z.string().nullable(),
+    cssClass: z.string().nullable(),
+    templateId: z.string().nullable(),
+    text: z.string().nullable(),
+    textColor: z.enum(["dark", "light"]).nullable(),
+});
+export const REDDIT_POST_SCHEMA = z.object({
+    archived: z.boolean(),
+    author: z.string().nullable(),
+    body: z.string(),
+    commentCount: z.number().int().nonnegative(),
+    createdAt: z.date(),
+    editedAt: z.date().nullable(),
+    flair: REDDIT_FLAIR_SCHEMA,
+    hidden: z.boolean(),
+    id: REDDIT_POST_ID_SCHEMA,
+    isLocked: z.boolean(),
+    isNsfw: z.boolean(),
+    isSelfPost: z.boolean(),
+    isSpoiler: z.boolean(),
+    isStickied: z.boolean(),
+    permalink: z.url(),
+    saved: z.boolean(),
+    score: z.number().int(),
+    shortId: z.string().min(1),
+    subreddit: z.string(),
+    subredditId: z.string(),
+    title: z.string(),
+    upvoteRatio: z.number().min(0).max(1),
+    url: z.url(),
+});
+export const REDDIT_COMMENT_SCHEMA = z.object({
+    author: z.string().nullable(),
+    body: z.string(),
+    createdAt: z.date(),
+    depth: z.number().int().nonnegative(),
+    distinguished: z.enum(["admin", "moderator", "special"]).nullable(),
+    editedAt: z.date().nullable(),
+    id: z.string().regex(/^t1_[a-z0-9]+$/i),
+    isPostAuthor: z.boolean(),
+    isStickied: z.boolean(),
+    parentId: REDDIT_THING_ID_SCHEMA,
+    permalink: z.url(),
+    postId: REDDIT_POST_ID_SCHEMA,
+    saved: z.boolean(),
+    score: z.number().int(),
+    shortId: z.string().min(1),
+    subreddit: z.string(),
+});
+export const REDDIT_MESSAGE_SCHEMA = z.object({
+    author: z.string().nullable(),
+    body: z.string(),
+    context: z.string(),
+    createdAt: z.date(),
+    destination: z.string(),
+    id: REDDIT_INBOX_ID_SCHEMA,
+    isNew: z.boolean(),
+    parentId: z.string().nullable(),
+    permalink: z.url().nullable(),
+    shortId: z.string().min(1),
+    subject: z.string(),
+    subreddit: z.string().nullable(),
+    wasComment: z.boolean(),
+});
+export const REDDIT_SUBREDDIT_SCHEMA = z.object({
+    activeUserCount: z.number().int().nonnegative().nullable(),
+    createdAt: z.date(),
+    description: z.string(),
+    displayName: z.string(),
+    id: z.string().regex(/^t5_[a-z0-9]+$/i),
+    isNsfw: z.boolean(),
+    name: z.string(),
+    publicDescription: z.string(),
+    subscribers: z.number().int().nonnegative(),
+    title: z.string(),
+    url: z.url(),
+    userIsSubscriber: z.boolean(),
+});
+export const REDDIT_PROFILE_SCHEMA = z.object({
+    commentKarma: z.number().int(),
+    createdAt: z.date(),
+    hasVerifiedEmail: z.boolean().nullable(),
+    id: z.string().min(1),
+    isEmployee: z.boolean(),
+    isModerator: z.boolean(),
+    linkKarma: z.number().int(),
+    username: z.string(),
+});
+export const REDDIT_PAGE_INFO_SCHEMA = z.object({
+    after: z.string().nullable(),
+    before: z.string().nullable(),
+});
+export const REDDIT_POST_PAGE_SCHEMA = z.object({
+    pageInfo: REDDIT_PAGE_INFO_SCHEMA,
+    posts: REDDIT_POST_SCHEMA.array(),
+});
+export const REDDIT_CONTENT_PAGE_SCHEMA = z.object({
+    content: z.union([REDDIT_POST_SCHEMA, REDDIT_COMMENT_SCHEMA]).array(),
+    pageInfo: REDDIT_PAGE_INFO_SCHEMA,
+});
+export const REDDIT_MESSAGE_PAGE_SCHEMA = z.object({
+    messages: REDDIT_MESSAGE_SCHEMA.array(),
+    pageInfo: REDDIT_PAGE_INFO_SCHEMA,
+});
+export const REDDIT_POST_FLAIR_TEMPLATE_SCHEMA = z.object({
+    backgroundColor: z.string(),
+    cssClass: z.string(),
+    id: z.string(),
+    isEditable: z.boolean(),
+    text: z.string(),
+    textColor: z.enum(["dark", "light"]),
+});
+export const REDDIT_PROVIDER_PROFILE_SCHEMA = z.looseObject({
+    comment_karma: z.number().int(),
+    created_utc: z.number(),
+    has_verified_email: z.boolean().nullable(),
+    id: z.string().min(1),
+    is_employee: z.boolean(),
+    is_mod: z.boolean(),
+    link_karma: z.number().int(),
+    name: z.string(),
+});
+export const REDDIT_PROVIDER_POST_SCHEMA = z.looseObject({
+    archived: z.boolean().default(false),
+    author: z.string().nullable().catch(null),
+    created_utc: z.number(),
+    edited: REDDIT_EDITED_SCHEMA.catch(false),
+    hidden: z.boolean().default(false),
+    id: z.string().min(1),
+    is_self: z.boolean().default(false),
+    link_flair_background_color: z.string().nullable().catch(null),
+    link_flair_css_class: z.string().nullable().catch(null),
+    link_flair_template_id: z.string().nullable().catch(null),
+    link_flair_text: z.string().nullable().catch(null),
+    link_flair_text_color: z.enum(["dark", "light"]).nullable().catch(null),
+    locked: z.boolean().default(false),
+    name: REDDIT_POST_ID_SCHEMA,
+    num_comments: z.number().int().nonnegative().default(0),
+    over_18: z.boolean().default(false),
+    permalink: z.string(),
+    saved: z.boolean().default(false),
+    score: z.number().int().default(0),
+    selftext: z.string().default(""),
+    spoiler: z.boolean().default(false),
+    stickied: z.boolean().default(false),
+    subreddit: z.string(),
+    subreddit_id: z.string(),
+    title: z.string(),
+    upvote_ratio: z.number().min(0).max(1).default(0),
+    url: z.string(),
+});
+export const REDDIT_PROVIDER_COMMENT_SCHEMA = z.looseObject({
+    author: z.string().nullable().catch(null),
+    body: z.string().default(""),
+    created_utc: z.number(),
+    depth: z.number().int().nonnegative().default(0),
+    distinguished: z
+        .enum(["admin", "moderator", "special"])
+        .nullable()
+        .catch(null),
+    edited: REDDIT_EDITED_SCHEMA.catch(false),
+    id: z.string().min(1),
+    is_submitter: z.boolean().default(false),
+    link_id: REDDIT_POST_ID_SCHEMA,
+    name: z.string().regex(/^t1_[a-z0-9]+$/i),
+    parent_id: REDDIT_THING_ID_SCHEMA,
+    permalink: z.string(),
+    saved: z.boolean().default(false),
+    score: z.number().int().default(0),
+    stickied: z.boolean().default(false),
+    subreddit: z.string(),
+});
+export const REDDIT_PROVIDER_MESSAGE_SCHEMA = z.looseObject({
+    author: z.string().nullable().catch(null),
+    body: z.string().default(""),
+    context: z.string().default(""),
+    created_utc: z.number(),
+    dest: z.string().default(""),
+    id: z.string().min(1),
+    name: REDDIT_INBOX_ID_SCHEMA,
+    new: z.boolean().default(false),
+    parent_id: z.string().nullable().catch(null),
+    permalink: z.string().nullable().catch(null),
+    subject: z.string().default(""),
+    subreddit: z.string().nullable().catch(null),
+    was_comment: z.boolean().default(false),
+});
+export const REDDIT_PROVIDER_SUBREDDIT_SCHEMA = z.looseObject({
+    active_user_count: z.number().int().nonnegative().nullable().catch(null),
+    created_utc: z.number(),
+    description: z.string().default(""),
+    display_name: z.string(),
+    display_name_prefixed: z.string(),
+    name: z.string().regex(/^t5_[a-z0-9]+$/i),
+    over18: z.boolean().default(false),
+    public_description: z.string().default(""),
+    subscribers: z.number().int().nonnegative().default(0),
+    title: z.string(),
+    url: z.string(),
+    user_is_subscriber: z.boolean().nullable().catch(null),
+});
+export const REDDIT_PROVIDER_POST_THING_SCHEMA = z.object({
+    data: REDDIT_PROVIDER_POST_SCHEMA,
+    kind: z.literal("t3"),
+});
+export const REDDIT_PROVIDER_COMMENT_THING_SCHEMA = z.object({
+    data: REDDIT_PROVIDER_COMMENT_SCHEMA,
+    kind: z.literal("t1"),
+});
+export const REDDIT_PROVIDER_MESSAGE_THING_SCHEMA = z.object({
+    data: REDDIT_PROVIDER_MESSAGE_SCHEMA,
+    kind: z.literal("t4"),
+});
+export const REDDIT_PROVIDER_INBOX_THING_SCHEMA = z.union([
+    REDDIT_PROVIDER_MESSAGE_THING_SCHEMA,
+    z.object({
+        data: REDDIT_PROVIDER_MESSAGE_SCHEMA,
+        kind: z.literal("t1"),
+    }),
+]);
+export const REDDIT_PROVIDER_SUBREDDIT_THING_SCHEMA = z.object({
+    data: REDDIT_PROVIDER_SUBREDDIT_SCHEMA,
+    kind: z.literal("t5"),
+});
+export const REDDIT_PROVIDER_CONTENT_THING_SCHEMA = z.union([
+    REDDIT_PROVIDER_POST_THING_SCHEMA,
+    REDDIT_PROVIDER_COMMENT_THING_SCHEMA,
+]);
+/** Builds one provider listing schema with exact child contracts. */
+/** @param childSchema - Schema for one listing child. */
+export function redditProviderListingSchema(childSchema) {
+    return z.object({
+        data: z.object({
+            after: z.string().nullable(),
+            before: z.string().nullable(),
+            children: childSchema.array(),
+        }),
+        kind: z.literal("Listing"),
+    });
+}
+export const REDDIT_PROVIDER_POST_LISTING_SCHEMA = redditProviderListingSchema(REDDIT_PROVIDER_POST_THING_SCHEMA);
+export const REDDIT_PROVIDER_CONTENT_LISTING_SCHEMA = redditProviderListingSchema(REDDIT_PROVIDER_CONTENT_THING_SCHEMA);
+export const REDDIT_PROVIDER_MESSAGE_LISTING_SCHEMA = redditProviderListingSchema(REDDIT_PROVIDER_INBOX_THING_SCHEMA);
+export const REDDIT_PROVIDER_FLAIR_TEMPLATE_SCHEMA = z.looseObject({
+    background_color: z.string().default(""),
+    css_class: z.string().default(""),
+    flair_template_id: z.string(),
+    flair_text_editable: z.boolean().default(false),
+    flair_text: z.string().default(""),
+    text_color: z.enum(["dark", "light"]).default("dark"),
+});
+/** Converts a Reddit provider post into the stable public post shape. */
+/** @param post - Parsed provider post. */
+export function toRedditPost(post) {
+    return REDDIT_POST_SCHEMA.parse({
+        archived: post.archived,
+        author: post.author,
+        body: post.selftext,
+        commentCount: post.num_comments,
+        createdAt: new Date(post.created_utc * 1_000),
+        editedAt: post.edited === false ? null : new Date(post.edited * 1_000),
+        flair: {
+            backgroundColor: post.link_flair_background_color,
+            cssClass: post.link_flair_css_class,
+            templateId: post.link_flair_template_id,
+            text: post.link_flair_text,
+            textColor: post.link_flair_text_color,
+        },
+        hidden: post.hidden,
+        id: post.name,
+        isLocked: post.locked,
+        isNsfw: post.over_18,
+        isSelfPost: post.is_self,
+        isSpoiler: post.spoiler,
+        isStickied: post.stickied,
+        permalink: new URL(post.permalink, REDDIT_ORIGIN).toString(),
+        saved: post.saved,
+        score: post.score,
+        shortId: post.id,
+        subreddit: post.subreddit,
+        subredditId: post.subreddit_id,
+        title: post.title,
+        upvoteRatio: post.upvote_ratio,
+        url: new URL(post.url, REDDIT_ORIGIN).toString(),
+    });
+}
+/** Converts a Reddit provider comment into the stable public comment shape. */
+/** @param comment - Parsed provider comment. */
+export function toRedditComment(comment) {
+    return REDDIT_COMMENT_SCHEMA.parse({
+        author: comment.author,
+        body: comment.body,
+        createdAt: new Date(comment.created_utc * 1_000),
+        depth: comment.depth,
+        distinguished: comment.distinguished,
+        editedAt: comment.edited === false ? null : new Date(comment.edited * 1_000),
+        id: comment.name,
+        isPostAuthor: comment.is_submitter,
+        isStickied: comment.stickied,
+        parentId: comment.parent_id,
+        permalink: new URL(comment.permalink, REDDIT_ORIGIN).toString(),
+        postId: comment.link_id,
+        saved: comment.saved,
+        score: comment.score,
+        shortId: comment.id,
+        subreddit: comment.subreddit,
+    });
+}
+/** Converts a Reddit inbox record into the stable public message shape. */
+/** @param message - Parsed provider inbox record. */
+export function toRedditMessage(message) {
+    return REDDIT_MESSAGE_SCHEMA.parse({
+        author: message.author,
+        body: message.body,
+        context: message.context,
+        createdAt: new Date(message.created_utc * 1_000),
+        destination: message.dest,
+        id: message.name,
+        isNew: message.new,
+        parentId: message.parent_id,
+        permalink: message.permalink
+            ? new URL(message.permalink, REDDIT_ORIGIN).toString()
+            : null,
+        shortId: message.id,
+        subject: message.subject,
+        subreddit: message.subreddit,
+        wasComment: message.was_comment,
+    });
+}
+/** Converts a Reddit subreddit thing into the stable public shape. */
+/** @param subreddit - Parsed provider subreddit. */
+export function toRedditSubreddit(subreddit) {
+    return REDDIT_SUBREDDIT_SCHEMA.parse({
+        activeUserCount: subreddit.active_user_count,
+        createdAt: new Date(subreddit.created_utc * 1_000),
+        description: subreddit.description,
+        displayName: subreddit.display_name,
+        id: subreddit.name,
+        isNsfw: subreddit.over18,
+        name: subreddit.display_name_prefixed,
+        publicDescription: subreddit.public_description,
+        subscribers: subreddit.subscribers,
+        title: subreddit.title,
+        url: new URL(subreddit.url, REDDIT_ORIGIN).toString(),
+        userIsSubscriber: subreddit.user_is_subscriber ?? false,
+    });
+}
+/** Converts a Reddit identity response into the stable public profile shape. */
+/** @param profile - Parsed provider identity. */
+export function toRedditProfile(profile) {
+    return REDDIT_PROFILE_SCHEMA.parse({
+        commentKarma: profile.comment_karma,
+        createdAt: new Date(profile.created_utc * 1_000),
+        hasVerifiedEmail: profile.has_verified_email,
+        id: profile.id,
+        isEmployee: profile.is_employee,
+        isModerator: profile.is_mod,
+        linkKarma: profile.link_karma,
+        username: profile.name,
+    });
+}
+/** Converts provider listing cursors into stable public pagination metadata. */
+/**
+ * @param listing - Parsed provider listing.
+ * @param listing.data - Provider listing data.
+ * @param listing.data.after - Forward cursor.
+ * @param listing.data.before - Backward cursor.
+ */
+export function toRedditPageInfo(listing) {
+    return REDDIT_PAGE_INFO_SCHEMA.parse({
+        after: listing.data.after,
+        before: listing.data.before,
+    });
+}

package/dist/triggers.d.ts

@@ -18,6 +18,7 @@ import type { linearTriggerContracts } from "./linear/index.js";
 import type { millionVerifierTriggerContracts } from "./millionverifier/index.js";
 import type { notionTriggerContracts } from "./notion/index.js";
 import type { outlookTriggerContracts } from "./outlook/index.js";
+import type { redditTriggerContracts } from "./reddit/index.js";
 import type { resendTriggerContracts } from "./resend/index.js";
 import type { slackTriggerContracts } from "./slack/index.js";
 import type { stripeTriggerContracts } from "./stripe/index.js";
@@ -27,7 +28,7 @@ import type { vercelTriggerContracts } from "./vercel/index.js";
 import type { webflowTriggerContracts } from "./webflow/index.js";
 import type { whatsappTriggerContracts } from "./whatsapp/index.js";
 import type { z } from "zod";
-export type TriggerContractMap = typeof airtableTriggerContracts & typeof apifyTriggerContracts & typeof automateTriggerContracts & typeof asanaTriggerContracts & typeof brevoTriggerContracts & typeof convexTriggerContracts & typeof closeTriggerContracts & typeof cloudflareTriggerContracts & typeof githubTriggerContracts & typeof gmailTriggerContracts & typeof googleCalendarTriggerContracts & typeof googleDriveTriggerContracts & typeof googleFormsTriggerContracts & typeof googleMeetTriggerContracts & typeof googleSheetsTriggerContracts & typeof hubspotTriggerContracts & typeof linearTriggerContracts & typeof millionVerifierTriggerContracts & typeof notionTriggerContracts & typeof outlookTriggerContracts & typeof resendTriggerContracts & typeof slackTriggerContracts & typeof stripeTriggerContracts & typeof teamsTriggerContracts & typeof trelloTriggerContracts & typeof vercelTriggerContracts & typeof webflowTriggerContracts & typeof whatsappTriggerContracts;
+export type TriggerContractMap = typeof airtableTriggerContracts & typeof apifyTriggerContracts & typeof automateTriggerContracts & typeof asanaTriggerContracts & typeof brevoTriggerContracts & typeof convexTriggerContracts & typeof closeTriggerContracts & typeof cloudflareTriggerContracts & typeof githubTriggerContracts & typeof gmailTriggerContracts & typeof googleCalendarTriggerContracts & typeof googleDriveTriggerContracts & typeof googleFormsTriggerContracts & typeof googleMeetTriggerContracts & typeof googleSheetsTriggerContracts & typeof hubspotTriggerContracts & typeof linearTriggerContracts & typeof millionVerifierTriggerContracts & typeof notionTriggerContracts & typeof outlookTriggerContracts & typeof redditTriggerContracts & typeof resendTriggerContracts & typeof slackTriggerContracts & typeof stripeTriggerContracts & typeof teamsTriggerContracts & typeof trelloTriggerContracts & typeof vercelTriggerContracts & typeof webflowTriggerContracts & typeof whatsappTriggerContracts;
 export type IntegrationTriggerType = keyof TriggerContractMap;
 /** Canonical authoring configuration for one integration trigger type. */
 export type TriggerConfig<TType extends IntegrationTriggerType> = z.input<TriggerContractMap[TType]["configSchema"]> extends Record<string, never> ? object : z.input<TriggerContractMap[TType]["configSchema"]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automate.ax/integration-contracts",
-  "version": "0.125.0",
+  "version": "0.126.0",
   "description": "Shared integration payload contracts and provider primitives for Automate.ax.",
   "license": "MIT",
   "repository": {
@@ -39,6 +39,7 @@
       "./millionverifier": "./src/millionverifier/index.ts",
       "./notion": "./src/notion/index.ts",
       "./outlook": "./src/outlook/index.ts",
+      "./reddit": "./src/reddit/index.ts",
       "./resend": "./src/resend/index.ts",
       "./slack": "./src/slack/index.ts",
       "./stripe": "./src/stripe/index.ts",
@@ -56,7 +57,7 @@
     }
   },
   "dependencies": {
-    "@automate.ax/codec": "0.125.0",
+    "@automate.ax/codec": "0.126.0",
     "@cfworker/json-schema": "^4.1.1",
     "@googleapis/calendar": "^15.0.0",
     "@googleapis/forms": "^6.0.1",
@@ -212,6 +213,11 @@
       "types": "./dist/outlook/index.d.ts",
       "default": "./dist/outlook/index.js"
     },
+    "./reddit": {
+      "bun": "./src/reddit/index.ts",
+      "types": "./dist/reddit/index.d.ts",
+      "default": "./dist/reddit/index.js"
+    },
     "./resend": {
       "bun": "./src/resend/index.ts",
       "types": "./dist/resend/index.d.ts",

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
+  }
+}