@robodev-ai/sdk 0.2.0

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@robodev-ai/sdk",
+  "version": "0.2.0",
+  "description": "Robodev SDK — defineDatabase, defineApi, and the injected Drizzle db",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/robodev-com/robodev-starbase.git",
+    "directory": "robodev-sdk"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "drizzle-orm": "^0.45.2",
+    "pg": "^8.16.3",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.15.5",
+    "typescript": "^5.9.2"
+  }
+}

package/src/api.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import type { RobodevDb } from "./db.js";
+
+/** Marker written onto every `defineApi(...)` result so Starbase can register the handler. */
+export const API_KIND = "robodevApi";
+
+/** Injected into every handler: tenant `db`, parsed query/body, and request headers. */
+export type ApiHandlerContext<TQuery, TBody> = {
+  db: RobodevDb;
+  query: TQuery;
+  body: TBody;
+  headers: Record<string, string | string[] | undefined>;
+};
+
+export type ApiDefinition<TQuery = unknown, TBody = unknown, TResponse = unknown> = {
+  _kind: typeof API_KIND;
+  query?: z.ZodType<TQuery>;
+  body?: z.ZodType<TBody>;
+  response?: z.ZodType<TResponse>;
+  handler: (ctx: ApiHandlerContext<TQuery, TBody>) => Promise<TResponse> | TResponse;
+};
+
+/**
+ * Defines one HTTP handler. Export as `get` / `post` / `put` / `patch` / `delete`
+ * from `api/<name>.ts` to serve that method at `/<name>`.
+ */
+export function defineApi<
+  TQuery extends z.ZodTypeAny | undefined = undefined,
+  TBody extends z.ZodTypeAny | undefined = undefined,
+  TResponse extends z.ZodTypeAny | undefined = undefined,
+>(config: {
+  query?: TQuery;
+  body?: TBody;
+  response?: TResponse;
+  handler: (
+    ctx: ApiHandlerContext<
+      TQuery extends z.ZodTypeAny ? z.infer<TQuery> : Record<string, never>,
+      TBody extends z.ZodTypeAny ? z.infer<TBody> : unknown
+    >,
+  ) =>
+    | Promise<TResponse extends z.ZodTypeAny ? z.infer<TResponse> : unknown>
+    | (TResponse extends z.ZodTypeAny ? z.infer<TResponse> : unknown);
+}): ApiDefinition<
+  TQuery extends z.ZodTypeAny ? z.infer<TQuery> : Record<string, never>,
+  TBody extends z.ZodTypeAny ? z.infer<TBody> : unknown,
+  TResponse extends z.ZodTypeAny ? z.infer<TResponse> : unknown
+> {
+  return {
+    _kind: API_KIND,
+    query: config.query,
+    body: config.body,
+    response: config.response,
+    handler: config.handler,
+  } as ApiDefinition<
+    TQuery extends z.ZodTypeAny ? z.infer<TQuery> : Record<string, never>,
+    TBody extends z.ZodTypeAny ? z.infer<TBody> : unknown,
+    TResponse extends z.ZodTypeAny ? z.infer<TResponse> : unknown
+  >;
+}
+
+export function isApiDefinition(value: unknown): value is ApiDefinition {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as ApiDefinition)._kind === API_KIND &&
+    typeof (value as ApiDefinition).handler === "function"
+  );
+}
+
+export const HTTP_METHODS = ["get", "post", "put", "patch", "delete"] as const;
+export type HttpMethod = (typeof HTTP_METHODS)[number];

package/src/database.ts

@@ -0,0 +1,46 @@
+import { is } from "drizzle-orm";
+import { PgTable } from "drizzle-orm/pg-core";
+
+/** Marker written onto every `defineDatabase(...)` result so Starbase can find the schema. */
+export const DATABASE_KIND = "robodevDatabase";
+
+export type DatabaseDef<TTables extends Record<string, unknown> = Record<string, unknown>> = {
+  _kind: typeof DATABASE_KIND;
+  name: string;
+  tables: TTables;
+};
+
+/**
+ * Declares a named Postgres database and its Drizzle tables.
+ * Default-export this from `database.ts`; `robodev deploy` creates/syncs it (no migration files).
+ */
+export function defineDatabase<TTables extends Record<string, unknown>>(config: {
+  name: string;
+  tables: TTables;
+}): DatabaseDef<TTables> {
+  if (!config.name || !/^[a-z][a-z0-9_]{0,47}$/.test(config.name)) {
+    throw new Error(
+      `Database name "${config.name}" must be lowercase, start with a letter, and use only a-z, 0-9, _`,
+    );
+  }
+  const tables = Object.entries(config.tables).filter(([, value]) => is(value, PgTable));
+  if (tables.length === 0) {
+    throw new Error("defineDatabase requires at least one pgTable(...)");
+  }
+  return {
+    _kind: DATABASE_KIND,
+    name: config.name,
+    tables: config.tables,
+  };
+}
+
+export function isDatabaseDef(value: unknown): value is DatabaseDef {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as DatabaseDef)._kind === DATABASE_KIND &&
+    typeof (value as DatabaseDef).name === "string" &&
+    typeof (value as DatabaseDef).tables === "object" &&
+    (value as DatabaseDef).tables !== null
+  );
+}

package/src/db.ts

@@ -0,0 +1,14 @@
+import { drizzle, type NodePgDatabase } from "drizzle-orm/node-postgres";
+import pg from "pg";
+
+export type RobodevDb<TSchema extends Record<string, unknown> = Record<string, unknown>> =
+  NodePgDatabase<TSchema>;
+
+/** Builds the Drizzle client Starbase injects as `ctx.db`. Used by the runtime, not app code. */
+export function createDb<TSchema extends Record<string, unknown>>(
+  connectionString: string,
+  schema: TSchema,
+): { db: RobodevDb<TSchema>; pool: pg.Pool } {
+  const pool = new pg.Pool({ connectionString, max: 5 });
+  return { db: drizzle(pool, { schema }), pool };
+}

package/src/drizzle.ts

@@ -0,0 +1,46 @@
+export {
+  and,
+  asc,
+  between,
+  desc,
+  eq,
+  exists,
+  getTableColumns,
+  getTableName,
+  gt,
+  gte,
+  ilike,
+  inArray,
+  isNotNull,
+  isNull,
+  like,
+  lt,
+  lte,
+  ne,
+  not,
+  notInArray,
+  or,
+  relations,
+  sql,
+} from "drizzle-orm";
+export type { InferInsertModel, InferSelectModel } from "drizzle-orm";
+export {
+  bigint,
+  boolean,
+  check,
+  date,
+  index,
+  integer,
+  jsonb,
+  numeric,
+  pgEnum,
+  pgTable,
+  primaryKey,
+  serial,
+  text,
+  timestamp,
+  unique,
+  uniqueIndex,
+  uuid,
+  varchar,
+} from "drizzle-orm/pg-core";

package/src/index.ts

@@ -0,0 +1,58 @@
+/** Public SDK: `defineDatabase`, `defineApi`, Zod, and the Drizzle helpers used in app code. */
+export { z } from "zod";
+export { defineDatabase, isDatabaseDef, DATABASE_KIND, type DatabaseDef } from "./database.js";
+export {
+  defineApi,
+  isApiDefinition,
+  HTTP_METHODS,
+  API_KIND,
+  type ApiDefinition,
+  type ApiHandlerContext,
+  type HttpMethod,
+} from "./api.js";
+export { createDb, type RobodevDb } from "./db.js";
+export {
+  and,
+  asc,
+  between,
+  bigint,
+  boolean,
+  check,
+  date,
+  desc,
+  eq,
+  exists,
+  getTableColumns,
+  getTableName,
+  gt,
+  gte,
+  ilike,
+  inArray,
+  index,
+  integer,
+  isNotNull,
+  isNull,
+  jsonb,
+  like,
+  lt,
+  lte,
+  ne,
+  not,
+  notInArray,
+  numeric,
+  or,
+  pgEnum,
+  pgTable,
+  primaryKey,
+  relations,
+  serial,
+  sql,
+  text,
+  timestamp,
+  unique,
+  uniqueIndex,
+  uuid,
+  varchar,
+  type InferInsertModel,
+  type InferSelectModel,
+} from "./drizzle.js";