@alchemy.run/turso 0.0.0 → 2.0.0-beta.85

package/src/Hrana.ts

@@ -0,0 +1,184 @@
+import { MigrationError, type SqlExecutor } from "@alchemy.run/sql/Migrations";
+import { splitSqlStatements } from "@alchemy.run/sql/SqlFile";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as HttpClient from "effect/http/HttpClient";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+import * as Redacted from "effect/Redacted";
+
+/**
+ * A minimal Hrana-over-HTTP client (`POST /v2/pipeline`) — the SQL wire
+ * protocol every Turso database speaks. Deploy-time work (migrations, SQL
+ * imports) uses it instead of `@libsql/client`, so the provider needs no
+ * driver and runs anywhere `HttpClient` does.
+ *
+ * @see https://github.com/tursodatabase/libsql/blob/main/docs/HRANA_3_SPEC.md
+ */
+export class HranaError extends Data.TaggedError("Turso::HranaError")<{
+  message: string;
+  code?: string;
+  cause?: unknown;
+}> {}
+
+type HranaValue =
+  | { type: "null" }
+  | { type: "integer"; value: string }
+  | { type: "float"; value: number }
+  | { type: "text"; value: string }
+  | { type: "blob"; base64: string };
+
+interface HranaStmt {
+  sql: string;
+  args?: HranaValue[];
+}
+
+interface HranaExecuteResult {
+  cols: Array<{ name: string | null }>;
+  rows: HranaValue[][];
+}
+
+interface HranaError_ {
+  message: string;
+  code?: string;
+}
+
+interface PipelineResponse {
+  results: Array<
+    | { type: "ok"; response: { type: string; result?: unknown } }
+    | { type: "error"; error: HranaError_ }
+  >;
+}
+
+const toHranaValue = (value: unknown): HranaValue => {
+  if (value === null || value === undefined) return { type: "null" };
+  if (typeof value === "bigint") return { type: "integer", value: value.toString() };
+  if (typeof value === "number") {
+    return Number.isInteger(value)
+      ? { type: "integer", value: value.toString() }
+      : { type: "float", value };
+  }
+  if (typeof value === "boolean") return { type: "integer", value: value ? "1" : "0" };
+  if (value instanceof Uint8Array) {
+    return { type: "blob", base64: Buffer.from(value).toString("base64") };
+  }
+  if (typeof value === "string") return { type: "text", value };
+  if (value instanceof Date) return { type: "text", value: value.toISOString() };
+  return { type: "text", value: JSON.stringify(value) };
+};
+
+const fromHranaValue = (value: HranaValue): unknown => {
+  switch (value.type) {
+    case "null":
+      return null;
+    case "integer":
+      return Number(value.value);
+    case "float":
+      return value.value;
+    case "text":
+      return value.value;
+    case "blob":
+      return Buffer.from(value.base64, "base64");
+  }
+};
+
+const toRows = (result: HranaExecuteResult): Array<Record<string, unknown>> =>
+  result.rows.map((row) =>
+    Object.fromEntries(
+      result.cols.map((col, i) => [col.name ?? String(i), fromHranaValue(row[i]!)]),
+    ),
+  );
+
+/** Connection details for one Turso database. */
+export interface HranaConnection {
+  /** `https://<hostname>` of the database. */
+  url: string;
+  /** A database auth token (JWT). */
+  authToken: Redacted.Redacted<string>;
+}
+
+const pipeline = (connection: HranaConnection, requests: ReadonlyArray<unknown>) =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const response = yield* client
+      .execute(
+        HttpClientRequest.post(`${connection.url.replace(/\/$/, "")}/v2/pipeline`).pipe(
+          HttpClientRequest.bearerToken(Redacted.value(connection.authToken)),
+          HttpClientRequest.bodyJsonUnsafe({ requests: [...requests, { type: "close" }] }),
+        ),
+      )
+      .pipe(Effect.mapError((cause) => new HranaError({ message: String(cause), cause })));
+    if (response.status < 200 || response.status >= 300) {
+      const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""));
+      return yield* new HranaError({
+        message: `Turso SQL request failed with HTTP ${response.status}: ${text}`,
+      });
+    }
+    const body = (yield* response.json.pipe(
+      Effect.mapError((cause) => new HranaError({ message: String(cause), cause })),
+    )) as unknown as PipelineResponse;
+    return body.results.slice(0, requests.length);
+  });
+
+/** Execute one statement and return its rows as objects. */
+export const query = (
+  connection: HranaConnection,
+  sql: string,
+  params?: ReadonlyArray<unknown>,
+): Effect.Effect<Array<Record<string, unknown>>, HranaError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const stmt: HranaStmt = { sql, args: (params ?? []).map(toHranaValue) };
+    const [result] = yield* pipeline(connection, [{ type: "execute", stmt }]);
+    if (result === undefined) {
+      return yield* new HranaError({ message: "Turso returned no result" });
+    }
+    if (result.type === "error") {
+      return yield* new HranaError({ message: result.error.message, code: result.error.code });
+    }
+    return toRows(result.response.result as HranaExecuteResult);
+  });
+
+/**
+ * Execute statements atomically. Each entry may hold several
+ * `;`-separated statements (a whole migration file or seed script), so they
+ * run as one Hrana `sequence` wrapped in `BEGIN`/`COMMIT`. A failing
+ * statement stops the sequence before `COMMIT`, and closing the stream
+ * rolls the open transaction back.
+ */
+export const transaction = (
+  connection: HranaConnection,
+  statements: ReadonlyArray<string>,
+): Effect.Effect<void, HranaError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const body = statements.flatMap(splitSqlStatements);
+    if (body.length === 0) return;
+    const sql = ["BEGIN", ...body.map((s) => s.replace(/;\s*$/, "")), "COMMIT"].join(";\n");
+    const [result] = yield* pipeline(connection, [{ type: "sequence", sql }]);
+    if (result === undefined) {
+      return yield* new HranaError({ message: "Turso returned no result" });
+    }
+    if (result.type === "error") {
+      return yield* new HranaError({ message: result.error.message, code: result.error.code });
+    }
+  });
+
+/** Adapt a Turso database connection into the migration registry's executor. */
+export const makeMigrationExecutor = (
+  connection: HranaConnection,
+  client: HttpClient.HttpClient,
+): SqlExecutor => {
+  const toMigrationError = (error: HranaError) =>
+    new MigrationError({ message: `turso: ${error.message}`, cause: error });
+  return {
+    dialect: "sqlite",
+    query: (sql, params) =>
+      query(connection, sql, params).pipe(
+        Effect.provideService(HttpClient.HttpClient, client),
+        Effect.mapError(toMigrationError),
+      ),
+    batch: (statements) =>
+      transaction(connection, statements).pipe(
+        Effect.provideService(HttpClient.HttpClient, client),
+        Effect.mapError(toMigrationError),
+      ),
+  };
+};

package/src/ManageDatabases.ts

@@ -0,0 +1,195 @@
+import { Credentials, DEFAULT_API_BASE_URL } from "@distilled.cloud/turso/Credentials";
+import * as turso from "@distilled.cloud/turso/turso";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import type * as HttpClient from "effect/http/HttpClient";
+import * as Layer from "effect/Layer";
+import { ApiToken } from "./ApiToken.ts";
+import type { ConnectClient } from "./Connect.ts";
+import type { DatabaseSeed } from "./Database.ts";
+import type { Group } from "./Group.ts";
+import { GroupToken } from "./GroupToken.ts";
+
+/** A database in the managed group. */
+export interface ManagedDatabase {
+  /** Database name. */
+  name: string;
+  /** Database UUID. */
+  dbId: string;
+  /** DNS hostname of the database. */
+  hostname: string;
+  /** libSQL URL (`libsql://<hostname>`). */
+  url: string;
+}
+
+export interface CreateManagedDatabaseOptions {
+  /** Seed the new database from an existing database (e.g. a template). */
+  seed?: DatabaseSeed;
+  /** Maximum size of the database, e.g. `"256mb"`. */
+  sizeLimit?: string;
+}
+
+export interface ManageDatabasesClient {
+  /** Create a database in the group. */
+  create(
+    name: string,
+    options?: CreateManagedDatabaseOptions,
+  ): Effect.Effect<ManagedDatabase, turso.CreateDatabaseError, RuntimeContext>;
+  /** Look up a database by name; `undefined` when it doesn't exist. */
+  get(
+    name: string,
+  ): Effect.Effect<ManagedDatabase | undefined, turso.GetDatabaseError, RuntimeContext>;
+  /** List every database in the group. */
+  list(): Effect.Effect<ManagedDatabase[], turso.ListDatabasesError, RuntimeContext>;
+  /** Delete a database. Deleting a missing database succeeds. */
+  delete(name: string): Effect.Effect<void, turso.DeleteDatabaseError, RuntimeContext>;
+  /**
+   * libSQL connection accessors for a database in the group, authorized by
+   * a group-wide SQL token. Pass to `SQL.LibSQL` or `Drizzle.LibSQL`.
+   */
+  connect(name: string): ConnectClient;
+}
+
+/**
+ * Let a Worker create, list, delete, and query databases in one Turso
+ * {@link Group}. Use it to give each customer their own database.
+ *
+ * The Worker gets an {@link ApiToken} that only works on that group, and a
+ * {@link GroupToken} for running SQL. It can't touch databases in any other
+ * group, and your own Turso API token stays on your machine.
+ *
+ * ### Database per tenant
+ * **Example:** Create a tenant database on signup and query it
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const tenants = yield* Turso.ManageDatabases(Tenants);
+ *   return {
+ *     fetch: Effect.gen(function* () {
+ *       const db = yield* tenants.create("acme");
+ *       const sql = yield* SQL.LibSQL(tenants.connect(db.name));
+ *       yield* sql`CREATE TABLE IF NOT EXISTS notes (body TEXT)`;
+ *       return HttpServerResponse.text(db.url);
+ *     }),
+ *   };
+ * }).pipe(Effect.provide(Turso.ManageDatabasesHttp));
+ * ```
+ *
+ * @binding
+ * @product Group
+ */
+export interface ManageDatabases extends Binding.Service<
+  ManageDatabases,
+  "Turso.ManageDatabases",
+  (group: Group) => Effect.Effect<ManageDatabasesClient>
+> {}
+
+export const ManageDatabases = Binding.Service<ManageDatabases>("Turso.ManageDatabases");
+
+/** Implementation over the Turso Platform API, usable from any Platform host. */
+export const ManageDatabasesHttp = Layer.effect(
+  ManageDatabases,
+  Effect.gen(function* () {
+    const PlatformToken = yield* ApiToken;
+    const SqlToken = yield* GroupToken;
+    return Effect.fn(function* (group: Group) {
+      const host = yield* Binding.Host;
+      const prefix = `${host?.LogicalId ?? ""}${group.LogicalId}`;
+      const apiToken = yield* PlatformToken(`${prefix}ManageToken`, {
+        group: group.name,
+        scopes: ["read", "db:create", "db:delete", "db:configure"],
+      });
+      const sqlToken = yield* SqlToken(`${prefix}SqlToken`, {
+        group: group.name,
+      });
+      const apiKey = yield* apiToken.token;
+      const authToken = yield* sqlToken.token;
+      const organization = yield* group.organization;
+      const groupName = yield* group.name;
+      const location = yield* group.location;
+
+      const authorize = <A, E>(
+        effect: Effect.Effect<A, E, Credentials | HttpClient.HttpClient>,
+      ): Effect.Effect<A, E, RuntimeContext> =>
+        effect.pipe(
+          Effect.provide(
+            Layer.mergeAll(
+              Layer.succeed(
+                Credentials,
+                Effect.map(apiKey, (key) => ({ apiKey: key, apiBaseUrl: DEFAULT_API_BASE_URL })),
+              ),
+              FetchHttpClient.layer,
+            ),
+          ),
+        );
+
+      const toManaged = (db: {
+        Name?: string;
+        DbId?: string;
+        Hostname?: string;
+      }): ManagedDatabase => ({
+        name: db.Name ?? "",
+        dbId: db.DbId ?? "",
+        hostname: db.Hostname ?? "",
+        url: `libsql://${db.Hostname}`,
+      });
+
+      const client: ManageDatabasesClient = {
+        create: (name, options) =>
+          authorize(
+            Effect.gen(function* () {
+              const { database } = yield* turso.createDatabase({
+                organizationSlug: yield* organization,
+                name,
+                group: yield* groupName,
+                seed: options?.seed,
+                size_limit: options?.sizeLimit,
+              });
+              return toManaged(database ?? {});
+            }),
+          ),
+        get: (name) =>
+          authorize(
+            Effect.gen(function* () {
+              const { database } = yield* turso.getDatabase({
+                organizationSlug: yield* organization,
+                databaseName: name,
+              });
+              return database && database.group === (yield* groupName)
+                ? toManaged(database)
+                : undefined;
+            }).pipe(Effect.catchTag("NotFound", () => Effect.undefined)),
+          ),
+        list: () =>
+          authorize(
+            Effect.gen(function* () {
+              const { databases } = yield* turso.listDatabases({
+                organizationSlug: yield* organization,
+                group: yield* groupName,
+              });
+              return (databases ?? []).map(toManaged);
+            }),
+          ),
+        delete: (name) =>
+          authorize(
+            Effect.gen(function* () {
+              yield* turso.deleteDatabase({
+                organizationSlug: yield* organization,
+                databaseName: name,
+              });
+            }).pipe(Effect.catchTag("NotFound", () => Effect.void)),
+          ),
+        connect: (name) => ({
+          // Turso hostnames are `<database>-<organization>.<location>.turso.io`,
+          // so the URL is derived without a Platform API round-trip.
+          url: Effect.gen(function* () {
+            return `libsql://${name}-${yield* organization}.${yield* location}.turso.io`;
+          }),
+          authToken,
+        }),
+      };
+      return client;
+    });
+  }),
+);

package/src/OrganizationInvite.ts

@@ -0,0 +1,118 @@
+import * as turso from "@distilled.cloud/turso/turso";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import { organization } from "./Credentials.ts";
+import type { Providers } from "./Providers.ts";
+
+/** Role granted to an invited or added organization member. */
+export type MemberRole = "admin" | "member" | "viewer";
+
+export interface OrganizationInviteProps {
+  /** Email address to invite. Changing it replaces the invite. */
+  email: string;
+  /**
+   * Role the invitee receives on accepting.
+   * @default "member"
+   */
+  role?: MemberRole;
+}
+
+export interface OrganizationInviteAttributes {
+  /** The invited email address. */
+  email: string;
+  /** The organization slug the invite is for. */
+  organization: string;
+  /** Role the invitee receives on accepting. */
+  role: string;
+}
+
+export type OrganizationInvite = Resource<
+  "Turso.OrganizationInvite",
+  OrganizationInviteProps,
+  OrganizationInviteAttributes,
+  never,
+  Providers
+>;
+
+/**
+ * An invitation for someone to join your Turso organization by email.
+ * Changing `role` re-sends the invite with the new role; destroying the
+ * resource withdraws a pending invite. Requires a team organization on a
+ * paid plan — the Starter plan rejects invites with `BadRequest`.
+ * @see https://docs.turso.tech/api-reference/organizations/invites/create
+ *
+ * ### Inviting Members
+ * **Example:** Invite a teammate as an admin
+ * ```typescript
+ * yield* Turso.OrganizationInvite("Alice", {
+ *   email: "alice@example.com",
+ *   role: "admin",
+ * });
+ * ```
+ *
+ * @resource
+ * @product Organization
+ */
+export const OrganizationInvite = Resource<OrganizationInvite>("Turso.OrganizationInvite");
+
+export const OrganizationInviteProvider = () =>
+  Provider.effect(
+    OrganizationInvite,
+    Effect.gen(function* () {
+      const observe = (org: string, email: string) =>
+        turso
+          .listOrganizationInvitesV2({ organizationSlug: org })
+          .pipe(
+            Effect.map(({ invites }) =>
+              (invites ?? []).find((i) => i.email?.toLowerCase() === email.toLowerCase()),
+            ),
+          );
+
+      const withdraw = (org: string, email: string) =>
+        turso.deleteOrganizationInviteByEmailV2({ organizationSlug: org, email }).pipe(
+          Effect.asVoid,
+          Effect.catchTag("NotFound", () => Effect.void),
+        );
+
+      return {
+        stables: ["email", "organization"],
+        diff: Effect.fn(function* ({ olds, news }) {
+          if (!isResolved(news)) return undefined;
+          if (news.email.toLowerCase() !== olds?.email.toLowerCase()) {
+            return { action: "replace" } as const;
+          }
+        }),
+        read: Effect.fn(function* ({ olds, output }) {
+          const org = output?.organization ?? (yield* organization);
+          const invite = yield* observe(org, output?.email ?? olds.email);
+          if (!invite?.email) return undefined;
+          return { email: invite.email, organization: org, role: invite.role ?? "member" };
+        }),
+        reconcile: Effect.fn(function* ({ news, output }) {
+          const org = output?.organization ?? (yield* organization);
+          const role = news.role ?? "member";
+
+          // Observe
+          const invite = yield* observe(org, news.email);
+
+          // Ensure / sync — invites have no update API, so a role change
+          // withdraws and re-sends.
+          if (invite?.role === role) {
+            return { email: invite.email ?? news.email, organization: org, role };
+          }
+          if (invite) yield* withdraw(org, news.email);
+          const { invited } = yield* turso.inviteOrganizationMemberV2({
+            organizationSlug: org,
+            email: news.email,
+            role,
+          });
+          return { email: invited?.email ?? news.email, organization: org, role };
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* withdraw(output.organization, output.email);
+        }),
+      };
+    }),
+  );

package/src/OrganizationMember.ts

@@ -0,0 +1,122 @@
+import * as turso from "@distilled.cloud/turso/turso";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import { organization } from "./Credentials.ts";
+import type { MemberRole } from "./OrganizationInvite.ts";
+import type { Providers } from "./Providers.ts";
+
+export interface OrganizationMemberProps {
+  /** Username of an existing Turso user. Changing it replaces the member. */
+  username: string;
+  /**
+   * Role of the member in the organization.
+   * @default "member"
+   */
+  role?: MemberRole;
+}
+
+export interface OrganizationMemberAttributes {
+  /** Username of the member. */
+  username: string;
+  /** The organization slug. */
+  organization: string;
+  /** Role of the member. */
+  role: string;
+  /** Email of the member. */
+  email: string | undefined;
+}
+
+export type OrganizationMember = Resource<
+  "Turso.OrganizationMember",
+  OrganizationMemberProps,
+  OrganizationMemberAttributes,
+  never,
+  Providers
+>;
+
+/**
+ * Adds an existing Turso user to your organization with a role, and keeps
+ * that role in sync. Destroying the resource removes the member. Use
+ * {@link OrganizationInvite} for people who don't have a Turso account
+ * yet. Requires a team organization on a paid plan.
+ * @see https://docs.turso.tech/api-reference/organizations/members/add
+ *
+ * ### Managing Members
+ * **Example:** Add a user as a viewer
+ * ```typescript
+ * yield* Turso.OrganizationMember("Bob", {
+ *   username: "bob",
+ *   role: "viewer",
+ * });
+ * ```
+ *
+ * @resource
+ * @product Organization
+ */
+export const OrganizationMember = Resource<OrganizationMember>("Turso.OrganizationMember");
+
+export const OrganizationMemberProvider = () =>
+  Provider.effect(
+    OrganizationMember,
+    Effect.gen(function* () {
+      const observe = (org: string, username: string) =>
+        turso.getOrganizationMember({ organizationSlug: org, username }).pipe(
+          Effect.map(({ member }) => member),
+          Effect.catchTag("NotFound", () => Effect.undefined),
+        );
+
+      return {
+        stables: ["username", "organization"],
+        diff: Effect.fn(function* ({ olds, news }) {
+          if (!isResolved(news)) return undefined;
+          if (news.username !== olds?.username) return { action: "replace" } as const;
+        }),
+        read: Effect.fn(function* ({ olds, output }) {
+          const org = output?.organization ?? (yield* organization);
+          const member = yield* observe(org, output?.username ?? olds.username);
+          if (!member?.username) return undefined;
+          return {
+            username: member.username,
+            organization: org,
+            role: member.role ?? "member",
+            email: member.email,
+          };
+        }),
+        reconcile: Effect.fn(function* ({ news, output }) {
+          const org = output?.organization ?? (yield* organization);
+          const role = news.role ?? "member";
+
+          // Observe
+          let member = yield* observe(org, news.username);
+
+          // Ensure
+          if (!member) {
+            yield* turso
+              .addOrganizationMember({ organizationSlug: org, username: news.username, role })
+              .pipe(Effect.catchTag("Conflict", () => Effect.void));
+            member = yield* observe(org, news.username);
+          }
+
+          // Sync role
+          if (member?.role !== role) {
+            yield* turso.updateMemberRole({
+              organizationSlug: org,
+              username: news.username,
+              role,
+            });
+          }
+          return { username: news.username, organization: org, role, email: member?.email };
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* turso
+            .removeOrganizationMember({
+              organizationSlug: output.organization,
+              username: output.username,
+            })
+            .pipe(Effect.catchTag("NotFound", () => Effect.void));
+        }),
+      };
+    }),
+  );