@gaganref/convex-api-keys 0.1.0

package/src/client/__tests__/setup.test.ts

@@ -0,0 +1,31 @@
+/// <reference types="vite/client" />
+import { test } from "vitest";
+import { convexTest } from "convex-test";
+import {
+  defineSchema,
+  type GenericSchema,
+  type SchemaDefinition,
+  componentsGeneric,
+} from "convex/server";
+import type { ComponentApi } from "../../component/_generated/component.js";
+import componentSchema from "../../component/schema.js";
+import { register } from "../../test.js";
+
+export const modules = import.meta.glob("../**/*.*s");
+export const componentModules = import.meta.glob("../../component/**/*.ts");
+
+export { componentSchema };
+
+export const components = componentsGeneric() as unknown as {
+  apiKeys: ComponentApi;
+};
+
+export function initConvexTest<
+  Schema extends SchemaDefinition<GenericSchema, boolean>,
+>(schema?: Schema) {
+  const t = convexTest(schema ?? defineSchema({}), modules);
+  register(t);
+  return t;
+}
+
+test("setup", () => {});

package/src/client/_generated/_ignore.ts

@@ -0,0 +1 @@
+// This is only here so convex-test can detect a _generated folder

package/src/client/crypto.ts

@@ -0,0 +1,64 @@
+import { runtimeUnavailableError } from "./errors.js";
+
+const textEncoder = new TextEncoder();
+
+export function generateToken(prefix: string, keyLengthBytes: number): string {
+  const bytes = randomBytes(keyLengthBytes);
+  return `${prefix}${base64UrlEncode(bytes)}`;
+}
+
+export async function sha256Base64Url(value: string): Promise<string> {
+  const hash = await getSubtleOrThrow().digest(
+    "SHA-256",
+    textEncoder.encode(value),
+  );
+  return base64UrlEncode(new Uint8Array(hash));
+}
+
+export function tokenLast4(token: string) {
+  return token.slice(-4);
+}
+
+function randomBytes(length: number) {
+  const crypto = getCryptoOrThrow();
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  return bytes;
+}
+
+function getSubtleOrThrow() {
+  const subtle = getCryptoOrThrow().subtle;
+  if (!subtle) {
+    throw runtimeUnavailableError(
+      "Web Crypto API subtle crypto is not available",
+    );
+  }
+  return subtle;
+}
+
+function getCryptoOrThrow() {
+  const crypto = globalThis.crypto;
+  if (!crypto) {
+    throw runtimeUnavailableError(
+      "Web Crypto API is not available in this runtime",
+    );
+  }
+  return crypto;
+}
+
+function base64UrlEncode(bytes: Uint8Array) {
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  if (typeof globalThis.btoa !== "function") {
+    throw runtimeUnavailableError(
+      "Base64 encoding is not available in this runtime",
+    );
+  }
+  return globalThis
+    .btoa(binary)
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/g, "");
+}

package/src/client/errors.ts

@@ -0,0 +1,67 @@
+export type ApiKeysClientErrorCode =
+  // Init-time — bad config passed to createApiKeys()
+  | "INVALID_OPTIONS"
+  // Call-time — programmer mistakes at call site
+  | "TOKEN_REQUIRED"
+  // Infrastructure
+  | "RUNTIME_UNAVAILABLE"
+  | "OPERATION_FAILED";
+
+/**
+ * Structured runtime error thrown by client-side helpers.
+ *
+ * Chains the underlying error via `cause`, making it visible in
+ * stack traces and debuggers.
+ *
+ * ```ts
+ * try {
+ *   await apiKeys.create(ctx, args);
+ * } catch (error) {
+ *   if (isApiKeysClientError(error)) {
+ *     console.error(error.code, error.message);
+ *     if (error.cause) console.error("Caused by:", error.cause);
+ *   }
+ * }
+ * ```
+ */
+export class ApiKeysClientError extends Error {
+  readonly name = "ApiKeysClientError";
+  readonly code: ApiKeysClientErrorCode;
+  readonly cause?: unknown;
+
+  constructor(code: ApiKeysClientErrorCode, message: string, cause?: unknown) {
+    super(message);
+    this.code = code;
+    this.cause = cause;
+  }
+}
+
+/**
+ * Type guard for structured API keys client errors.
+ */
+export function isApiKeysClientError(
+  error: unknown,
+): error is ApiKeysClientError {
+  return error instanceof ApiKeysClientError;
+}
+
+export function optionsError(message: string) {
+  return new ApiKeysClientError(
+    "INVALID_OPTIONS",
+    `api-keys options: ${message}`,
+  );
+}
+
+export function tokenRequiredError() {
+  return new ApiKeysClientError(
+    "TOKEN_REQUIRED",
+    "api-keys: token must not be empty",
+  );
+}
+
+export function runtimeUnavailableError(message: string) {
+  return new ApiKeysClientError(
+    "RUNTIME_UNAVAILABLE",
+    `api-keys runtime: ${message}`,
+  );
+}

package/src/client/index.ts

@@ -0,0 +1,44 @@
+export { ApiKeys, ApiKeys as default } from "./operations.js";
+
+export { ApiKeysClientError, isApiKeysClientError } from "./errors.js";
+export type { ApiKeysClientErrorCode } from "./errors.js";
+
+export type { ApiKeysOptions } from "./options.js";
+
+export { onInvalidateHookPayloadValidator } from "./types.js";
+
+export type {
+  ApiKeyId,
+  ApiKeyEventMetadata,
+  ApiKeyMetadata,
+  ApiKeyToken,
+  ApiKeysTypeOptions,
+  CleanupExpiredArgs,
+  CleanupExpiredResult,
+  CreateArgs,
+  CreateResult,
+  GetKeyArgs,
+  GetKeyResult,
+  InvalidateArgs,
+  InvalidateAllArgs,
+  InvalidateAllResult,
+  InvalidateResult,
+  ListEventsArgs,
+  ListEventsResult,
+  ListKeyEventsArgs,
+  ListKeyEventsResult,
+  ListKeysArgs,
+  ListKeysResult,
+  PaginationOptions,
+  OnInvalidateHookPayload,
+  RefreshArgs,
+  RefreshResult,
+  RunMutationCtx,
+  RunQueryCtx,
+  TouchArgs,
+  TouchResult,
+  UpdateArgs,
+  UpdateResult,
+  ValidateArgs,
+  ValidateResult,
+} from "./types.js";