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

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.succeed(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.succeed(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));
+        }),
+      };
+    }),
+  );

package/src/OrganizationSettings.ts

@@ -0,0 +1,145 @@
+import * as turso from "@distilled.cloud/turso/turso";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import * as Schedule from "effect/Schedule";
+import { organization } from "./Credentials.ts";
+import type { Providers } from "./Providers.ts";
+
+export interface OrganizationSettingsProps {
+  /** Allow usage beyond the plan's quota to be billed as overages. */
+  overages?: boolean;
+  /**
+   * Require every member to enable multi-factor authentication. The
+   * deploying user must have MFA enabled first.
+   */
+  requireMfa?: boolean;
+  /**
+   * Keep deleted databases and groups recoverable. Requires an admin or
+   * owner.
+   */
+  restoreEnabled?: boolean;
+}
+
+interface Settings {
+  overages: boolean;
+  requireMfa: boolean;
+  restoreEnabled: boolean;
+}
+
+export interface OrganizationSettingsAttributes extends Settings {
+  /** The organization slug. */
+  organization: string;
+  /** Settings observed before Alchemy first changed them; restored on destroy. */
+  original: Settings;
+}
+
+export type OrganizationSettings = Resource<
+  "Turso.OrganizationSettings",
+  OrganizationSettingsProps,
+  OrganizationSettingsAttributes,
+  never,
+  Providers
+>;
+
+/**
+ * Settings of the Turso organization your credentials act on. Only the
+ * settings you set are managed; destroying the resource restores the values
+ * observed before Alchemy first changed them.
+ * @see https://docs.turso.tech/api-reference/organizations/update
+ *
+ * ### Configuring the Organization
+ * **Example:** Enable overages and require MFA
+ * ```typescript
+ * yield* Turso.OrganizationSettings("Org", {
+ *   overages: true,
+ *   requireMfa: true,
+ * });
+ * ```
+ *
+ * @resource
+ * @product Organization
+ */
+export const OrganizationSettings = Resource<OrganizationSettings>("Turso.OrganizationSettings");
+
+const toSettings = (org: turso.Organization | undefined): Settings => ({
+  overages: org?.overages ?? false,
+  requireMfa: org?.require_mfa ?? false,
+  restoreEnabled: org?.restore_enabled ?? false,
+});
+
+export const OrganizationSettingsProvider = () =>
+  Provider.effect(
+    OrganizationSettings,
+    Effect.gen(function* () {
+      const observe = (slug: string) =>
+        turso
+          .getOrganization({ organizationSlug: slug })
+          .pipe(Effect.map(({ organization }) => toSettings(organization)));
+
+      // `restore_enabled` must be updated on its own (per the API).
+      const apply = (slug: string, observed: Settings, desired: Partial<Settings>) =>
+        Effect.gen(function* () {
+          const patch: { overages?: boolean; require_mfa?: boolean } = {};
+          if (desired.overages !== undefined && desired.overages !== observed.overages) {
+            patch.overages = desired.overages;
+          }
+          if (desired.requireMfa !== undefined && desired.requireMfa !== observed.requireMfa) {
+            patch.require_mfa = desired.requireMfa;
+          }
+          if (Object.keys(patch).length > 0) {
+            yield* turso.updateOrganization({ organizationSlug: slug, ...patch });
+          }
+          if (
+            desired.restoreEnabled !== undefined &&
+            desired.restoreEnabled !== observed.restoreEnabled
+          ) {
+            yield* turso.updateOrganization({
+              organizationSlug: slug,
+              restore_enabled: desired.restoreEnabled,
+            });
+          }
+        });
+
+      return {
+        stables: ["organization", "original"],
+        read: Effect.fn(function* ({ output }) {
+          if (!output) return undefined;
+          return { ...output, ...(yield* observe(output.organization)) };
+        }),
+        reconcile: Effect.fn(function* ({ news, output }) {
+          const slug = output?.organization ?? (yield* organization);
+          const observed = yield* observe(slug);
+          yield* apply(slug, observed, news);
+          // Organization reads can briefly lag a PATCH; wait until the
+          // settings we set are visible.
+          const settled = yield* observe(slug).pipe(
+            Effect.repeat({
+              schedule: Schedule.spaced("1 second"),
+              until: (current) =>
+                (news.overages === undefined || current.overages === news.overages) &&
+                (news.requireMfa === undefined || current.requireMfa === news.requireMfa) &&
+                (news.restoreEnabled === undefined ||
+                  current.restoreEnabled === news.restoreEnabled),
+              times: 10,
+            }),
+          );
+          return {
+            organization: slug,
+            original: output?.original ?? observed,
+            ...settled,
+          };
+        }),
+        delete: Effect.fn(function* ({ olds, output }) {
+          const observed = yield* observe(output.organization);
+          // Restore only the settings this resource managed.
+          yield* apply(output.organization, observed, {
+            overages: olds.overages !== undefined ? output.original.overages : undefined,
+            requireMfa: olds.requireMfa !== undefined ? output.original.requireMfa : undefined,
+            restoreEnabled:
+              olds.restoreEnabled !== undefined ? output.original.restoreEnabled : undefined,
+          });
+        }),
+      };
+    }),
+  );

package/src/Providers.ts

@@ -0,0 +1,67 @@
+import { CredentialsStoreLive } from "alchemy/Auth/Credentials";
+import { ProfileStoreLive } from "alchemy/Auth/Profile";
+import * as Provider from "alchemy/Provider";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as Layer from "effect/Layer";
+import { ApiToken, ApiTokenProvider } from "./ApiToken.ts";
+import { TursoAuth } from "./AuthProvider.ts";
+import * as Credentials from "./Credentials.ts";
+import { Database, DatabaseProvider } from "./Database.ts";
+import { DatabaseToken, DatabaseTokenProvider } from "./DatabaseToken.ts";
+import { Group, GroupProvider } from "./Group.ts";
+import { GroupToken, GroupTokenProvider } from "./GroupToken.ts";
+import { OrganizationInvite, OrganizationInviteProvider } from "./OrganizationInvite.ts";
+import { OrganizationMember, OrganizationMemberProvider } from "./OrganizationMember.ts";
+import { OrganizationSettings, OrganizationSettingsProvider } from "./OrganizationSettings.ts";
+
+/**
+ * Service tag bundling all Turso providers + auth + credentials. Use
+ * `Turso.providers()` to materialize the full layer.
+ */
+export class Providers extends Provider.ProviderCollection<Providers>()("Turso") {}
+
+export type ProviderRequirements = Layer.Services<ReturnType<typeof providers>>;
+
+/**
+ * Build the complete Turso providers Layer: every Turso resource, the
+ * Turso AuthProvider registration (so `alchemy profile edit` can configure
+ * it), and credential resolution.
+ *
+ * @example
+ * ```ts
+ * Alchemy.Stack("App", { providers: Turso.providers() }, ...)
+ * ```
+ */
+export const providers = () =>
+  Layer.effect(
+    Providers,
+    Provider.collection([
+      ApiToken,
+      Database,
+      DatabaseToken,
+      Group,
+      GroupToken,
+      OrganizationInvite,
+      OrganizationMember,
+      OrganizationSettings,
+    ]),
+  ).pipe(
+    Layer.provide(
+      Layer.mergeAll(
+        ApiTokenProvider(),
+        DatabaseProvider(),
+        DatabaseTokenProvider(),
+        GroupProvider(),
+        GroupTokenProvider(),
+        OrganizationInviteProvider(),
+        OrganizationMemberProvider(),
+        OrganizationSettingsProvider(),
+      ),
+    ),
+    Layer.provideMerge(Credentials.fromAuthProvider()),
+    Layer.provideMerge(FetchHttpClient.layer),
+    Layer.provideMerge(TursoAuth),
+    Layer.provideMerge(ProfileStoreLive),
+    Layer.provideMerge(CredentialsStoreLive),
+    Layer.orDie,
+  );

package/src/index.ts

@@ -0,0 +1,20 @@
+export * from "./ApiToken.ts";
+export * from "./AuthProvider.ts";
+export * from "./Connect.ts";
+export {
+  Credentials,
+  CredentialsFromEnv,
+  DEFAULT_API_BASE_URL,
+  fromAuthProvider,
+  fromToken,
+  Organization,
+} from "./Credentials.ts";
+export * from "./Database.ts";
+export * from "./DatabaseToken.ts";
+export * from "./Group.ts";
+export * from "./GroupToken.ts";
+export * from "./ManageDatabases.ts";
+export * from "./OrganizationInvite.ts";
+export * from "./OrganizationMember.ts";
+export * from "./OrganizationSettings.ts";
+export * from "./Providers.ts";