@alienplatform/bindings 1.0.0 → 2.0.0

package/src/global.ts

@@ -1,316 +0,0 @@
-/**
- * Global convenience functions for Alien bindings.
- *
- * These functions use a singleton AlienContext for easy access.
- */
-
-import type { ArtifactRegistry } from "./bindings/artifact-registry.js"
-import type { Build } from "./bindings/build.js"
-import type { FunctionBinding } from "./bindings/function.js"
-import type { Kv } from "./bindings/kv.js"
-import type { Queue } from "./bindings/queue.js"
-import type { ServiceAccount } from "./bindings/service-account.js"
-import type { Storage } from "./bindings/storage.js"
-import type { Vault } from "./bindings/vault.js"
-import { command as commandImpl } from "./commands.js"
-import { AlienContext } from "./context.js"
-import {
-  type CronEvent,
-  type QueueMessageEvent,
-  type StorageEvent,
-  onCronEvent as onCronEventImpl,
-  onQueueMessage as onQueueMessageImpl,
-  onStorageEvent as onStorageEventImpl,
-} from "./events.js"
-import { waitUntil as waitUntilImpl } from "./wait-until.js"
-
-// Lazy-initialized global context
-let globalContext: AlienContext | undefined
-
-/**
- * Get or create the global AlienContext.
- */
-async function getGlobalContext(): Promise<AlienContext> {
-  if (!globalContext) {
-    globalContext = await AlienContext.fromEnv()
-  }
-  return globalContext
-}
-
-// ============================================================================
-// Binding Accessors
-// ============================================================================
-
-/**
- * Get a storage binding.
- *
- * @param name - Binding name
- * @returns Storage binding instance
- *
- * @example
- * ```typescript
- * import { storage } from "@alienplatform/bindings"
- *
- * const bucket = await storage("my-bucket")
- * await bucket.put("hello.txt", "Hello, World!")
- * ```
- */
-export async function storage(name: string): Promise<Storage> {
-  return (await getGlobalContext()).storage(name)
-}
-
-/**
- * Get a KV binding.
- *
- * @param name - Binding name
- * @returns KV binding instance
- *
- * @example
- * ```typescript
- * import { kv } from "@alienplatform/bindings"
- *
- * const cache = await kv("my-cache")
- * await cache.set("key", "value")
- * const value = await cache.getText("key")
- * ```
- */
-export async function kv(name: string): Promise<Kv> {
-  return (await getGlobalContext()).kv(name)
-}
-
-/**
- * Get a queue binding.
- *
- * @param name - Binding name
- * @returns Queue binding instance
- *
- * @example
- * ```typescript
- * import { queue } from "@alienplatform/bindings"
- *
- * const tasks = await queue("task-queue")
- * await tasks.send("job-type", { jobId: "123" })
- * ```
- */
-export async function queue(name: string): Promise<Queue> {
-  return (await getGlobalContext()).queue(name)
-}
-
-/**
- * Get a vault binding.
- *
- * @param name - Binding name
- * @returns Vault binding instance
- *
- * @example
- * ```typescript
- * import { vault } from "@alienplatform/bindings"
- *
- * const secrets = await vault("app-secrets")
- * const apiKey = await secrets.get("API_KEY")
- * ```
- */
-export async function vault(name: string): Promise<Vault> {
-  return (await getGlobalContext()).vault(name)
-}
-
-/**
- * Get a build binding.
- *
- * @param name - Binding name
- * @returns Build binding instance
- *
- * @example
- * ```typescript
- * import { build } from "@alienplatform/bindings"
- *
- * const builder = await build("my-builder")
- * const execution = await builder.start({ script: "npm run build" })
- * ```
- */
-export async function build(name: string): Promise<Build> {
-  return (await getGlobalContext()).build(name)
-}
-
-/**
- * Get an artifact registry binding.
- *
- * @param name - Binding name
- * @returns ArtifactRegistry binding instance
- *
- * @example
- * ```typescript
- * import { artifactRegistry } from "@alienplatform/bindings"
- *
- * const registry = await artifactRegistry("my-registry")
- * const repo = await registry.createRepository("my-app")
- * ```
- */
-export async function artifactRegistry(name: string): Promise<ArtifactRegistry> {
-  return (await getGlobalContext()).artifactRegistry(name)
-}
-
-/**
- * Get a function binding.
- *
- * @param name - Binding name
- * @returns Function binding instance
- *
- * @example
- * ```typescript
- * import { func } from "@alienplatform/bindings"
- *
- * const processor = await func("image-processor")
- * const result = await processor.invokeJson("resize", { width: 800 })
- * ```
- */
-export async function func(name: string): Promise<FunctionBinding> {
-  return (await getGlobalContext()).func(name)
-}
-
-/**
- * Get a service account binding.
- *
- * @param name - Binding name
- * @returns ServiceAccount binding instance
- *
- * @example
- * ```typescript
- * import { serviceAccount } from "@alienplatform/bindings"
- *
- * const sa = await serviceAccount("deployment-account")
- * const info = await sa.getInfo()
- * ```
- */
-export async function serviceAccount(name: string): Promise<ServiceAccount> {
-  return (await getGlobalContext()).serviceAccount(name)
-}
-
-// ============================================================================
-// Event Handlers
-// ============================================================================
-
-/**
- * Register a storage event handler.
- *
- * @param bucket - Bucket name
- * @param handler - Event handler
- * @param options - Handler options
- * @returns Unsubscribe function
- *
- * @example
- * ```typescript
- * import { onStorageEvent } from "@alienplatform/bindings"
- *
- * onStorageEvent("uploads", async (event) => {
- *   console.log("File uploaded:", event.objectKey)
- * })
- * ```
- */
-export function onStorageEvent(
-  bucket: string,
-  handler: (event: StorageEvent) => Promise<void>,
-  options?: { prefix?: string },
-): () => void {
-  return onStorageEventImpl(bucket, handler, options)
-}
-
-/**
- * Register a cron event handler.
- *
- * @param schedule - Cron schedule expression
- * @param handler - Event handler
- * @returns Unsubscribe function
- *
- * @example
- * ```typescript
- * import { onCronEvent } from "@alienplatform/bindings"
- *
- * onCronEvent("0 * * * *", async (event) => {
- *   console.log("Hourly task running at:", event.timestamp)
- * })
- * ```
- */
-export function onCronEvent(
-  schedule: string,
-  handler: (event: CronEvent) => Promise<void>,
-): () => void {
-  return onCronEventImpl(schedule, handler)
-}
-
-/**
- * Register a queue message handler.
- *
- * @param queueName - Queue name
- * @param handler - Message handler
- * @returns Unsubscribe function
- *
- * @example
- * ```typescript
- * import { onQueueMessage } from "@alienplatform/bindings"
- *
- * onQueueMessage("tasks", async (message) => {
- *   console.log("Processing:", message.payload)
- * })
- * ```
- */
-export function onQueueMessage<T = unknown>(
-  queueName: string,
-  handler: (message: QueueMessageEvent<T>) => Promise<void>,
-): () => void {
-  return onQueueMessageImpl(queueName, handler)
-}
-
-// ============================================================================
-// Commands
-// ============================================================================
-
-/**
- * Register a CLI command.
- *
- * @param name - Command name
- * @param description - Command description
- * @param handler - Command handler
- *
- * @example
- * ```typescript
- * import { command } from "@alienplatform/bindings"
- *
- * command("migrate", "Run database migrations", async (args) => {
- *   await runMigrations()
- *   return 0
- * })
- * ```
- */
-export function command(
-  name: string,
-  _description: string,
-  handler: (args: string[]) => Promise<number>,
-): void {
-  commandImpl(name, handler)
-}
-
-// ============================================================================
-// WaitUntil
-// ============================================================================
-
-/**
- * Register a background task to continue after the response.
- *
- * @param promise - The promise to track
- *
- * @example
- * ```typescript
- * import { waitUntil } from "@alienplatform/bindings"
- *
- * export default {
- *   async fetch(request: Request): Promise<Response> {
- *     waitUntil(sendAnalytics(request))
- *     return Response.json({ status: "ok" })
- *   }
- * }
- * ```
- */
-export function waitUntil(promise: Promise<unknown>): void {
-  waitUntilImpl(promise)
-}

package/src/grpc-utils.ts

@@ -1,159 +0,0 @@
-/**
- * gRPC utility functions for error handling and type conversion.
- */
-
-import { AlienError } from "@alienplatform/core"
-import { Status } from "nice-grpc"
-import {
-  BindingNotFoundError,
-  GrpcCallError,
-  KvInvalidKeyError,
-  KvInvalidValueError,
-  KvKeyNotFoundError,
-  SecretNotFoundError,
-  StorageObjectExistsError,
-  StorageObjectNotFoundError,
-  StoragePreconditionError,
-} from "./errors.js"
-
-/**
- * Convert a gRPC error to an AlienError with proper chaining.
- */
-export async function grpcErrorToAlienError(
-  error: unknown,
-  service: string,
-  method: string,
-  context?: {
-    bindingName?: string
-    path?: string
-    key?: string
-    secretName?: string
-    bindingType?: string
-  },
-): Promise<AlienError<any>> {
-  // Start with the original error wrapped as AlienError
-  const baseError = await AlienError.from(error)
-
-  // Handle nice-grpc errors
-  if (error && typeof error === "object" && "code" in error) {
-    const grpcError = error as { code: number; details?: string; message?: string }
-    const details = grpcError.details ?? grpcError.message ?? "Unknown error"
-    const code = grpcError.code
-
-    // Map specific gRPC status codes to domain errors
-    if (code === Status.NOT_FOUND) {
-      // Determine the appropriate not-found error based on context
-      if (context?.path && context?.bindingName) {
-        return baseError.withContext(
-          StorageObjectNotFoundError.create({
-            bindingName: context.bindingName,
-            path: context.path,
-          }),
-        )
-      }
-      if (context?.key && context?.bindingName) {
-        return baseError.withContext(
-          KvKeyNotFoundError.create({
-            bindingName: context.bindingName,
-            key: context.key,
-          }),
-        )
-      }
-      if (context?.secretName && context?.bindingName) {
-        return baseError.withContext(
-          SecretNotFoundError.create({
-            bindingName: context.bindingName,
-            secretName: context.secretName,
-          }),
-        )
-      }
-      if (context?.bindingName && context?.bindingType) {
-        return baseError.withContext(
-          BindingNotFoundError.create({
-            bindingName: context.bindingName,
-            bindingType: context.bindingType,
-          }),
-        )
-      }
-    }
-
-    if (code === Status.FAILED_PRECONDITION && context?.path && context?.bindingName) {
-      return baseError.withContext(
-        StoragePreconditionError.create({
-          bindingName: context.bindingName,
-          path: context.path,
-          condition: details,
-        }),
-      )
-    }
-
-    if (code === Status.ALREADY_EXISTS && context?.path && context?.bindingName) {
-      return baseError.withContext(
-        StorageObjectExistsError.create({
-          bindingName: context.bindingName,
-          path: context.path,
-        }),
-      )
-    }
-
-    if (code === Status.INVALID_ARGUMENT) {
-      if (context?.key) {
-        return baseError.withContext(
-          KvInvalidKeyError.create({
-            key: context.key,
-            reason: details,
-          }),
-        )
-      }
-      if (service === "KvService") {
-        return baseError.withContext(
-          KvInvalidValueError.create({
-            reason: details,
-          }),
-        )
-      }
-    }
-
-    // Generic gRPC error
-    return baseError.withContext(
-      GrpcCallError.create({
-        service,
-        method,
-        grpcCode: Status[code] ?? String(code),
-        details,
-      }),
-    )
-  }
-
-  // Fallback for non-gRPC errors
-  return baseError.withContext(
-    GrpcCallError.create({
-      service,
-      method,
-      grpcCode: "UNKNOWN",
-      details: error instanceof Error ? error.message : String(error),
-    }),
-  )
-}
-
-/**
- * Wrap an async gRPC call with error handling.
- */
-export async function wrapGrpcCall<T>(
-  service: string,
-  method: string,
-  call: () => Promise<T>,
-  context?: {
-    bindingName?: string
-    path?: string
-    key?: string
-    secretName?: string
-    bindingType?: string
-  },
-): Promise<T> {
-  try {
-    return await call()
-  } catch (error) {
-    throw await grpcErrorToAlienError(error, service, method, context)
-  }
-}

package/src/index.ts

@@ -1,156 +0,0 @@
-/**
- * @alienplatform/bindings - TypeScript SDK for Alien bindings.
- *
- * This package provides type-safe access to Alien resources including
- * Storage, KV, Queue, Vault, Build, ArtifactRegistry, Function, and ServiceAccount.
- *
- * @example
- * ```typescript
- * // Global convenience functions (most common usage)
- * import { storage, kv, onStorageEvent, waitUntil } from "@alienplatform/bindings"
- *
- * const bucket = storage("my-bucket")
- * await bucket.put("hello.txt", "Hello, World!")
- *
- * // Or use AlienContext for more control
- * import { AlienContext } from "@alienplatform/bindings"
- *
- * const ctx = AlienContext.fromEnv()
- * const bucket = ctx.storage("my-bucket")
- * ```
- *
- * @packageDocumentation
- */
-
-// ============================================================================
-// Main Entry Point
-// ============================================================================
-
-export { AlienContext } from "./context.js"
-
-// ============================================================================
-// Global Convenience Functions
-// ============================================================================
-
-export {
-  // Binding accessors
-  storage,
-  kv,
-  queue,
-  vault,
-  build,
-  artifactRegistry,
-  func,
-  serviceAccount,
-  // Event handlers
-  onStorageEvent,
-  onCronEvent,
-  onQueueMessage,
-  // Commands
-  command,
-  // WaitUntil
-  waitUntil,
-} from "./global.js"
-
-// Event types - StorageEvent, QueueMessage, ScheduledEvent come from @alienplatform/core
-// CronEvent and QueueMessageEvent are bindings-specific extensions
-export type {
-  StorageEvent,
-  StorageEventType,
-  QueueMessage,
-  ScheduledEvent,
-  CronEvent,
-  QueueMessageEvent,
-} from "./events.js"
-
-// ============================================================================
-// Binding Classes (for advanced usage)
-// ============================================================================
-
-export { Storage } from "./bindings/storage.js"
-export { Kv } from "./bindings/kv.js"
-export { Queue } from "./bindings/queue.js"
-export { Vault } from "./bindings/vault.js"
-export { Build } from "./bindings/build.js"
-export { ArtifactRegistry } from "./bindings/artifact-registry.js"
-export { FunctionBinding } from "./bindings/function.js"
-export { ServiceAccount } from "./bindings/service-account.js"
-
-// ============================================================================
-// Types
-// ============================================================================
-
-export type {
-  // Storage
-  StorageGetOptions,
-  StoragePutOptions,
-  StorageObjectMeta,
-  StorageGetResult,
-  StorageListResult,
-  SignedUrlOptions,
-  SignedUrlResult,
-  // KV
-  KvPutOptions,
-  KvScanResult,
-  // Queue
-  ReceivedQueueMessage,
-  // Build (BuildStatus and ComputeType come from @alienplatform/core)
-  BuildStartConfig,
-  BuildExecution,
-  // Artifact Registry
-  ArtifactRegistryPermissions,
-  RepositoryInfo,
-  ArtifactRegistryCredentials,
-  ComputeServiceType,
-  AwsCrossAccountAccess,
-  GcpCrossAccountAccess,
-  CrossAccountAccess,
-  CrossAccountPermissions,
-  // Function
-  FunctionInvokeRequest,
-  FunctionInvokeResponse,
-  // Service Account
-  ServiceAccountInfo,
-  AwsServiceAccountInfo,
-  GcpServiceAccountInfo,
-  AzureServiceAccountInfo,
-  ImpersonationRequest,
-  // Configuration
-  AlienBindingsConfig,
-  AlienBindingsProvider,
-} from "./types.js"
-
-// ============================================================================
-// Errors
-// ============================================================================
-
-export {
-  GrpcConnectionError,
-  GrpcCallError,
-  BindingNotFoundError,
-  ContextNotInitializedError,
-  MissingEnvVarError,
-  StorageObjectNotFoundError,
-  StoragePreconditionError,
-  StorageObjectExistsError,
-  KvKeyNotFoundError,
-  KvInvalidKeyError,
-  KvInvalidValueError,
-  SecretNotFoundError,
-  QueueOperationError,
-  EventHandlerAlreadyRegisteredError,
-  CommandAlreadyRegisteredError,
-  InvalidBindingConfigError,
-} from "./errors.js"
-
-// ============================================================================
-// Commands
-// ============================================================================
-
-export { runCommand, getCommands, type CommandDefinition } from "./commands.js"
-
-// ============================================================================
-// Re-export from core for convenience
-// ============================================================================
-
-// Note: BuildStatus, ComputeType are re-exported via types.ts