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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alchemy.run/turso",
-  "version": "0.0.0",
+  "version": "2.0.0-beta.85",
   "description": "Turso databases, groups and tokens for Alchemy.",
   "keywords": [
     "alchemy",
@@ -9,12 +9,63 @@
     "libsql",
     "turso"
   ],
+  "homepage": "https://alchemy.run",
+  "bugs": {
+    "url": "https://github.com/alchemy-run/alchemy/issues"
+  },
   "license": "Apache-2.0",
   "author": "Sam Goodwin <sam@alchemy.run>",
-  "homepage": "https://alchemy.run",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/alchemy-run/alchemy.git",
     "directory": "packages/turso"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "bun": "./src/index.ts",
+      "worker": "./src/index.ts",
+      "default": "./lib/index.js"
+    },
+    "./*": {
+      "types": "./lib/*.d.ts",
+      "bun": "./src/*.ts",
+      "worker": "./src/*.ts",
+      "default": "./lib/*.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@alchemy.run/sql": "2.0.0-beta.85",
+    "@distilled.cloud/core": "1.0.0-rc.18",
+    "@distilled.cloud/turso": "1.0.0-rc.18"
+  },
+  "devDependencies": {
+    "@types/bun": "1.4.3",
+    "alchemy": "2.0.0-beta.85",
+    "effect": "^4.1.0",
+    "typescript": "^7.0.2"
+  },
+  "peerDependencies": {
+    "alchemy": "2.0.0-beta.85",
+    "effect": "^4.1.0"
+  },
+  "alchemy": {
+    "contributes": [
+      "@alchemy.run/turso/Contributions"
+    ]
+  },
+  "scripts": {
+    "build": "pnpm -r --filter \"{.}...\" run build:package",
+    "build:package": "node scripts/build.ts"
   }
-}
+}

package/src/ApiToken.ts

@@ -0,0 +1,207 @@
+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 Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { organization } from "./Credentials.ts";
+import type { Providers } from "./Providers.ts";
+
+export class ApiTokenUnexpectedResponse extends Data.TaggedError("ApiTokenUnexpectedResponse")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+/**
+ * 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, previous }) {
+          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 generation a delete-first replacement is about to revoke.
+          if (previous !== undefined && previous.id === observed.id) return previous;
+          // 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* new ApiTokenUnexpectedResponse({
+              message: `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* AuthError.make({
+      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,112 @@
+import { ConfigError } from "@distilled.cloud/core/errors";
+import { Credentials, DEFAULT_API_BASE_URL } from "@distilled.cloud/turso/Credentials";
+import * as turso from "@distilled.cloud/turso/turso";
+import { lazyCredentials, orDieCredentialsUnavailable } 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 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, ConfigError>,
+): Effect.Effect<Context.Context<Credentials | Organization>, never, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const http = yield* HttpClient.HttpClient;
+    const credentials = Effect.map(resolve, (creds) => ({
+      apiKey: creds.apiToken,
+      apiBaseUrl: creds.apiBaseUrl,
+    }));
+    // `Organization` is typed as never failing, so a credentials failure dies
+    // here; the engine still reports it as `CredentialsRequired`.
+    const organization = yield* resolve.pipe(
+      Effect.orDie,
+      Effect.flatMap((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),
+            ),
+      ),
+      Effect.cached,
+    );
+    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;
+}) =>
+  Effect.succeed<TursoResolvedCredentials>({
+    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" },
+  }).pipe(make, Layer.effectContext);
+
+/**
+ * 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(
+    lazyCredentials<TursoResolvedCredentials, ConfigError>()(
+      TURSO_AUTH_PROVIDER_NAME,
+      (creds) => creds,
+    ).pipe(Effect.flatMap(make)),
+  );