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

package/src/ApiToken.ts

@@ -0,0 +1,197 @@
+import * as turso from "@distilled.cloud/turso/turso";
+import { Unowned } from "alchemy/AdoptPolicy";
+import { deepEqual, isResolved } from "alchemy/Diff";
+import { createPhysicalName } from "alchemy/PhysicalName";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { organization } from "./Credentials.ts";
+import type { Providers } from "./Providers.ts";
+
+/**
+ * A permission granted to a group-scoped API token. `read-only` and
+ * `full-access` are presets that expand to individual scopes.
+ */
+export type ApiTokenScope =
+  | "read"
+  | "db:create"
+  | "db:delete"
+  | "db:configure"
+  | "db:mint-token"
+  | "db:rotate-creds"
+  | "group:configure"
+  | "group:mint-token"
+  | "group:rotate-creds"
+  | "read-only"
+  | "full-access";
+
+export interface ApiTokenProps {
+  /**
+   * Token name, unique within your account. If omitted, a unique name is
+   * generated from the stack, stage, and logical ID.
+   */
+  name?: string;
+  /**
+   * Restrict the token to one group of the organization (e.g.
+   * `group.name`). Requires `scopes`. Omit for an organization-scoped token.
+   */
+  group?: string;
+  /**
+   * Permissions of a group-scoped token. Required (and non-empty) when
+   * `group` is set. `db:mint-token` issues new SQL tokens;
+   * `db:rotate-creds` invalidates every SQL token of a database.
+   */
+  scopes?: ApiTokenScope[];
+}
+
+export interface ApiTokenAttributes {
+  /** Token ID. */
+  id: string;
+  /** Token name. */
+  name: string;
+  /** The organization slug the token is restricted to. */
+  organization: string;
+  /** The group the token is restricted to, if group-scoped. */
+  group: string | undefined;
+  /** The expanded scopes of a group-scoped token. */
+  scopes: string[];
+  /** The Platform API token, sent as `Authorization: Bearer <token>`. */
+  token: Redacted.Redacted<string>;
+}
+
+export type ApiToken = Resource<
+  "Turso.ApiToken",
+  ApiTokenProps,
+  ApiTokenAttributes,
+  never,
+  Providers
+>;
+
+/**
+ * A Turso API token. It lets an app create and delete groups and databases.
+ * To run SQL, use a {@link DatabaseToken} instead. Limit it to one group
+ * with `group` and `scopes` to give an app only the access it needs.
+ *
+ * Turso only shows the token once, when it's created, so Alchemy stores it
+ * in state as a `Redacted` value. Changing a prop creates a new token, and
+ * destroying it cancels the token.
+ * @see https://docs.turso.tech/api-reference/tokens/create
+ *
+ * ### Creating a Token
+ * **Example:** Token for the whole organization
+ * ```typescript
+ * const token = yield* Turso.ApiToken("Ci", {});
+ * ```
+ *
+ * **Example:** Token that can only create databases in one group
+ * ```typescript
+ * const token = yield* Turso.ApiToken("Tenants", {
+ *   group: group.name,
+ *   scopes: ["read", "db:create", "db:delete", "db:mint-token"],
+ * });
+ * ```
+ *
+ * @resource
+ * @product API Token
+ */
+export const ApiToken = Resource<ApiToken>("Turso.ApiToken");
+
+const tokenName = (id: string, name: string | undefined) =>
+  name ? Effect.succeed(name) : createPhysicalName({ id, maxLength: 64, delimiter: "-" });
+
+export const ApiTokenProvider = () =>
+  Provider.effect(
+    ApiToken,
+    Effect.gen(function* () {
+      const observe = (name: string) =>
+        turso
+          .listAPITokens({})
+          .pipe(Effect.map(({ tokens }) => (tokens ?? []).find((t) => t.name === name)));
+
+      const revoke = (name: string) =>
+        turso.revokeAPIToken({ tokenName: name }).pipe(
+          Effect.asVoid,
+          Effect.catchTag("NotFound", () => Effect.void),
+        );
+
+      return {
+        stables: ["id", "name", "organization", "group", "scopes", "token"],
+        diff: Effect.fn(function* ({ id, olds, news, output }) {
+          if (!isResolved(news)) return undefined;
+          const name = output?.name ?? (yield* tokenName(id, olds?.name));
+          // Turso tokens are immutable: any change mints a new one.
+          if (
+            (news.name !== undefined && news.name !== name) ||
+            news.group !== olds?.group ||
+            !deepEqual(news.scopes ?? [], olds?.scopes ?? [])
+          ) {
+            // A pinned name can't be held by two tokens at once.
+            return {
+              action: "replace",
+              deleteFirst: news.name !== undefined && news.name === name,
+            } as const;
+          }
+        }),
+        read: Effect.fn(function* ({ id, olds, output }) {
+          const name = output?.name ?? (yield* tokenName(id, olds?.name));
+          const observed = yield* observe(name);
+          if (!observed) return undefined;
+          if (output !== undefined && output.id === observed.id) return output;
+          // The secret is only revealed at creation, so a token we have no
+          // state for can't be adopted with its value — reconcile re-mints.
+          return Unowned({
+            id: observed.id ?? "",
+            name,
+            organization: observed.organization ?? "",
+            group: observed.group,
+            scopes: observed.scopes ?? [],
+            token: Redacted.make(""),
+          });
+        }),
+        reconcile: Effect.fn(function* ({ id, news, output, session }) {
+          const org = output?.organization ?? (yield* organization);
+          const name = output?.name ?? (yield* tokenName(id, news.name));
+
+          // Observe
+          const observed = yield* observe(name);
+          if (
+            observed &&
+            output &&
+            Redacted.value(output.token) !== "" &&
+            output.id === observed.id
+          ) {
+            return output;
+          }
+
+          // Ensure — a token we hold no secret for (a lost create, or an
+          // adoption) is revoked and re-minted.
+          if (observed) {
+            yield* session.note(`Re-minting API token ${name}...`);
+            yield* revoke(name);
+          }
+          const created = yield* turso.createAPIToken({
+            tokenName: name,
+            organization: org,
+            group: news.group,
+            scopes: news.scopes,
+          });
+          if (!created.token || !created.id) {
+            return yield* Effect.fail(new Error(`Turso returned no token for ${name}`));
+          }
+          const minted = yield* observe(name);
+          return {
+            id: created.id,
+            name,
+            organization: minted?.organization ?? org,
+            group: minted?.group ?? news.group,
+            scopes: minted?.scopes ?? [],
+            token: created.token,
+          };
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* revoke(output.name);
+        }),
+      };
+    }),
+  );

package/src/AuthProvider.ts

@@ -0,0 +1,113 @@
+import { DEFAULT_API_BASE_URL } from "@distilled.cloud/turso/Credentials";
+import { AuthError } from "alchemy/Auth/AuthProvider";
+import { getEnv, getEnvRedacted } from "alchemy/Auth/Env";
+import {
+  makeStoredAuthProvider,
+  storedSecret,
+  storedValueText,
+  type StoredAuthConfig,
+} from "alchemy/Auth/StoredAuthProvider";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+
+/**
+ * Canonical name registered in the AuthProviders registry. Use this key to
+ * look up the Turso AuthProvider from inside provider Layers.
+ */
+export const TURSO_AUTH_PROVIDER_NAME = "Turso";
+
+export type TursoAuthConfig = StoredAuthConfig;
+
+/**
+ * Resolved Turso Platform API credentials.
+ *
+ * Turso has no OAuth application flow — the Platform API authenticates
+ * with API tokens only (`turso auth api-tokens mint <name>`). The
+ * organization is optional: when omitted it is discovered from the token
+ * (an organization-scoped token, or an account with a single organization).
+ */
+export interface TursoResolvedCredentials {
+  type: "apiToken";
+  apiToken: Redacted.Redacted<string>;
+  apiBaseUrl: string;
+  organization: string | undefined;
+  source: { type: TursoAuthConfig["method"] | "env"; details?: string };
+}
+
+const readEnvironment = Effect.gen(function* () {
+  const apiToken = yield* getEnvRedacted("TURSO_API_TOKEN");
+  const apiKey = yield* getEnvRedacted("TURSO_API_KEY");
+  const token = apiToken ?? apiKey;
+  if (token === undefined || Redacted.value(token).trim().length === 0) {
+    return yield* new AuthError({
+      message: "Turso CI credentials not found. Set TURSO_API_TOKEN or TURSO_API_KEY.",
+    });
+  }
+  return {
+    type: "apiToken" as const,
+    apiToken: Redacted.make(Redacted.value(token).trim()),
+    apiBaseUrl: (yield* getEnv("TURSO_API_BASE_URL")) ?? DEFAULT_API_BASE_URL,
+    organization: yield* getEnv("TURSO_ORGANIZATION"),
+    source: {
+      type: "env" as const,
+      details: apiToken === undefined ? "TURSO_API_KEY" : "TURSO_API_TOKEN",
+    },
+  } satisfies TursoResolvedCredentials;
+});
+
+const tursoAuth = makeStoredAuthProvider<TursoResolvedCredentials>({
+  provider: TURSO_AUTH_PROVIDER_NAME,
+  fields: [
+    {
+      name: "apiToken",
+      label: "Turso API Token",
+      description: "Mint one with `turso auth api-tokens mint alchemy`.",
+      secret: true,
+      validate: (value) => (value.trim().length === 0 ? "Required" : undefined),
+    },
+    {
+      name: "organization",
+      label: "Turso Organization (slug)",
+      description: "Defaults to the token's organization when it has exactly one.",
+      optional: true,
+    },
+  ],
+  toResolved: (values, source) => ({
+    type: "apiToken",
+    apiToken: storedSecret(values.apiToken) ?? Redacted.make(""),
+    apiBaseUrl: DEFAULT_API_BASE_URL,
+    organization: storedValueText(values.organization),
+    source: { type: source },
+  }),
+  readEnvironment,
+  environment: [
+    {
+      name: "TURSO_API_TOKEN",
+      required: true,
+      secret: true,
+      alternatives: ["TURSO_API_KEY"],
+      description: "Turso Platform API token.",
+    },
+    {
+      name: "TURSO_ORGANIZATION",
+      required: false,
+      description: "Organization slug; defaults to the token's only organization.",
+    },
+    {
+      name: "TURSO_API_BASE_URL",
+      required: false,
+      description: "Platform API base URL override.",
+    },
+  ],
+});
+
+/**
+ * Layer that registers the Turso AuthProvider into the AuthProviders
+ * registry when built. Included in `Turso.providers()` so the alchemy CLI
+ * (`alchemy profile edit`) can configure it.
+ */
+export const TursoAuth = tursoAuth.layer;
+
+/** Schema of Turso's inline API-token values. */
+export const TursoStoredCredentials = tursoAuth.storedSchema;
+export type TursoStoredCredentials = typeof TursoStoredCredentials.Type;

package/src/Connect.ts

@@ -0,0 +1,103 @@
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type * as Redacted from "effect/Redacted";
+import type { Database } from "./Database.ts";
+import { DatabaseToken, type TokenAuthorization } from "./DatabaseToken.ts";
+
+/**
+ * libSQL connection accessors for one Turso database. Resolving them does
+ * not open a connection; pass the client to `SQL.LibSQL` or
+ * `Drizzle.LibSQL`, or read `url` / `authToken` for `@libsql/client`.
+ */
+export interface ConnectClient {
+  /** libSQL URL of the database (`libsql://<hostname>`). */
+  url: Effect.Effect<string, never, RuntimeContext>;
+  /** SQL auth token for the database. */
+  authToken: Effect.Effect<Redacted.Redacted<string>, never, RuntimeContext>;
+}
+
+export interface ConnectOptions {
+  /**
+   * Access level of the token minted for this host.
+   * @default "full-access"
+   */
+  authorization?: TokenAuthorization;
+}
+
+/**
+ * Connect to a Turso database from a Worker, Lambda, or other host. The
+ * host gets the database's URL and its own {@link DatabaseToken}. Your
+ * Turso API token stays on your machine.
+ *
+ * ### Querying a Database
+ * **Example:** Effect SQL over a Turso database
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const conn = yield* Turso.Connect(Db);
+ *   const sql = yield* SQL.LibSQL(conn);
+ *   return {
+ *     fetch: Effect.gen(function* () {
+ *       return yield* HttpServerResponse.json(yield* sql`SELECT 1 AS value`);
+ *     }),
+ *   };
+ * }).pipe(Effect.provide(Turso.ConnectHttp));
+ * ```
+ *
+ * **Example:** Drizzle over a Turso database
+ * ```typescript
+ * const conn = yield* Turso.Connect(Db);
+ * const db = yield* Drizzle.LibSQL(conn, { relations });
+ * ```
+ *
+ * **Example:** AWS Lambda (install the native libSQL client)
+ * ```typescript
+ * export default class Api extends Lambda.Function<Api>()(
+ *   "Api",
+ *   { main: import.meta.url, build: { install: ["@libsql/client"] } },
+ *   Effect.gen(function* () {
+ *     const sql = yield* SQL.LibSQL(yield* Turso.Connect(Db));
+ *     // ...
+ *   }).pipe(Effect.provide(Turso.ConnectHttp)),
+ * ) {}
+ * ```
+ *
+ * **Example:** Read-only access
+ * ```typescript
+ * const conn = yield* Turso.Connect(Db, { authorization: "read-only" });
+ * ```
+ *
+ * @binding
+ * @product Database
+ */
+export interface Connect extends Binding.Service<
+  Connect,
+  "Turso.Connect",
+  (database: Database, options?: ConnectOptions) => Effect.Effect<ConnectClient>
+> {}
+
+export const Connect = Binding.Service<Connect>("Turso.Connect");
+
+/**
+ * Host-independent implementation: the URL and a per-host token are bound
+ * as environment values, so it works on any Platform host.
+ */
+export const ConnectHttp = Layer.effect(
+  Connect,
+  Effect.gen(function* () {
+    const Token = yield* DatabaseToken;
+    return Effect.fn(function* (database: Database, options?: ConnectOptions) {
+      const host = yield* Binding.Host;
+      const authorization = options?.authorization ?? "full-access";
+      const token = yield* Token(
+        `${host?.LogicalId ?? ""}${database.LogicalId}${authorization === "read-only" ? "ReadOnly" : ""}Token`,
+        { database: database.name, authorization },
+      );
+      return {
+        url: yield* database.url,
+        authToken: yield* token.token,
+      } satisfies ConnectClient;
+    });
+  }),
+);

package/src/Contributions.ts

@@ -0,0 +1,9 @@
+import * as Contributions from "alchemy/Contributions";
+
+export default Contributions.make({
+  name: "turso",
+  auth: Contributions.lazy(
+    () => import("./AuthProvider.ts"),
+    (module) => module.TursoAuth,
+  ),
+});

package/src/Credentials.ts

@@ -0,0 +1,139 @@
+import { ConfigError } from "@distilled.cloud/core/errors";
+import {
+  Credentials,
+  DEFAULT_API_BASE_URL,
+  type Config as TursoClientConfig,
+} from "@distilled.cloud/turso/Credentials";
+import * as turso from "@distilled.cloud/turso/turso";
+import {
+  deferUntilFirstUse,
+  orDieCredentialsUnavailable,
+  resolveProviderConfig,
+} from "alchemy/Auth/Resolve";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as HttpClient from "effect/http/HttpClient";
+import * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import {
+  TURSO_AUTH_PROVIDER_NAME,
+  type TursoAuthConfig,
+  type TursoResolvedCredentials,
+} from "./AuthProvider.ts";
+
+export {
+  Credentials,
+  CredentialsFromEnv,
+  DEFAULT_API_BASE_URL,
+} from "@distilled.cloud/turso/Credentials";
+
+/**
+ * The Turso organization slug every org-scoped Platform API call targets.
+ * Holds an effect so the slug is resolved (and, when not configured,
+ * discovered from the API token) on first use, never at layer build.
+ */
+export class Organization extends Context.Service<Organization, Effect.Effect<string>>()(
+  "Turso.Organization",
+) {}
+
+/** The organization slug for the current Turso credentials. */
+export const organization = Effect.gen(function* () {
+  return yield* yield* Organization;
+});
+
+/**
+ * Discover the organization an API token acts on: the token's own
+ * organization when it is org-scoped, else the account's only organization.
+ */
+const discoverOrganization = Effect.gen(function* () {
+  const orgs = yield* turso.listOrganizations({});
+  if (orgs.length === 1 && orgs[0]?.slug) {
+    return orgs[0].slug;
+  }
+  return yield* new ConfigError({
+    message:
+      orgs.length === 0
+        ? "Turso: this API token has no organizations."
+        : `Turso: this API token can access ${orgs.length} organizations (${orgs
+            .map((org) => org.slug)
+            .join(", ")}). Set TURSO_ORGANIZATION or configure the organization in your profile.`,
+  });
+});
+
+const make = (
+  resolve: Effect.Effect<TursoResolvedCredentials>,
+): Effect.Effect<Context.Context<Credentials | Organization>, never, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const http = yield* HttpClient.HttpClient;
+    const cached = yield* Effect.cached(resolve);
+    const credentials: Effect.Effect<TursoClientConfig> = Effect.map(cached, (creds) => ({
+      apiKey: creds.apiToken,
+      apiBaseUrl: creds.apiBaseUrl,
+    }));
+    const organization = yield* Effect.cached(
+      Effect.flatMap(cached, (creds) =>
+        creds.organization !== undefined && creds.organization.length > 0
+          ? Effect.succeed(creds.organization)
+          : discoverOrganization.pipe(
+              Effect.provideService(Credentials, credentials),
+              Effect.provideService(HttpClient.HttpClient, http),
+              orDieCredentialsUnavailable(TURSO_AUTH_PROVIDER_NAME),
+            ),
+      ),
+    );
+    return Context.make(Credentials, credentials).pipe(Context.add(Organization, organization));
+  });
+
+/**
+ * Build Turso `Credentials` + `Organization` from an explicit API token.
+ * Useful for tests or when the caller already has a token in hand.
+ *
+ * @example
+ * ```ts
+ * Effect.provide(Turso.fromToken({ apiToken: "...", organization: "my-org" }))
+ * ```
+ */
+export const fromToken = (input: {
+  apiToken: string | Redacted.Redacted<string>;
+  organization?: string;
+  apiBaseUrl?: string;
+}) =>
+  Layer.effectContext(
+    make(
+      Effect.succeed({
+        type: "apiToken",
+        apiToken:
+          typeof input.apiToken === "string" ? Redacted.make(input.apiToken) : input.apiToken,
+        apiBaseUrl: input.apiBaseUrl ?? DEFAULT_API_BASE_URL,
+        organization: input.organization,
+        source: { type: "stored" },
+      }),
+    ),
+  );
+
+/**
+ * Build Turso `Credentials` + `Organization` that resolve through the
+ * Alchemy AuthProvider: environment credentials (`TURSO_API_TOKEN`) when
+ * present, otherwise the selected profile. Resolution is deferred until the
+ * first API call, so building the provider layers never needs a profile.
+ */
+export const fromAuthProvider = () =>
+  Layer.effectContext(
+    Effect.gen(function* () {
+      const resolve = yield* resolveProviderConfig<TursoAuthConfig, TursoResolvedCredentials>(
+        TURSO_AUTH_PROVIDER_NAME,
+      ).pipe(
+        Effect.flatMap(({ profileName, resolve }) =>
+          Effect.mapError(
+            resolve,
+            (e) =>
+              new ConfigError({
+                message: `Failed to resolve Turso credentials from ${profileName === undefined ? "the environment" : `profile '${profileName}'`}: ${e.message}`,
+              }),
+          ),
+        ),
+        deferUntilFirstUse,
+      );
+      return yield* make(resolve.pipe(orDieCredentialsUnavailable(TURSO_AUTH_PROVIDER_NAME)));
+    }),
+  );