@aigne/afs-s3 1.11.0-beta.6

package/LICENSE.md

@@ -0,0 +1,26 @@
+# Proprietary License
+
+Copyright (c) 2024-2025 ArcBlock, Inc. All Rights Reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. Unauthorized copying, modification, distribution, or use of
+this Software, via any medium, is strictly prohibited.
+
+The Software is provided for internal use only within ArcBlock, Inc. and its
+authorized affiliates.
+
+## No License Granted
+
+No license, express or implied, is granted to any party for any purpose.
+All rights are reserved by ArcBlock, Inc.
+
+## Public Artifact Distribution
+
+Portions of this Software may be released publicly under separate open-source
+licenses (such as MIT License) through designated public repositories. Such
+public releases are governed by their respective licenses and do not affect
+the proprietary nature of this repository.
+
+## Contact
+
+For licensing inquiries, contact: legal@arcblock.io

package/dist/index.d.mts

@@ -0,0 +1,282 @@
+import { AFSAccessMode, AFSBaseProvider, AFSDeleteResult, AFSEntry, AFSExecResult, AFSListResult, AFSModuleLoadParams, AFSStatResult, AFSWriteEntryPayload, AFSWriteResult, RouteContext } from "@aigne/afs";
+import { S3Client } from "@aws-sdk/client-s3";
+import * as zod0 from "zod";
+import { z } from "zod";
+
+//#region src/types.d.ts
+/**
+ * Configuration options for AFSS3
+ */
+interface AFSS3Options {
+  /** Module name (used as mount path segment) */
+  name?: string;
+  /** Module description */
+  description?: string;
+  /** S3 bucket name */
+  bucket: string;
+  /** Key prefix (optional) */
+  prefix?: string;
+  /** AWS region (defaults to environment) */
+  region?: string;
+  /** Access mode */
+  accessMode?: "readonly" | "readwrite";
+  /** Custom endpoint for S3-compatible services (MinIO, R2, B2) */
+  endpoint?: string;
+  /** Force path-style URLs (needed for some S3-compatible services) */
+  forcePathStyle?: boolean;
+  /** AWS credentials profile name */
+  profile?: string;
+  /** Explicit credentials (for testing or non-AWS environments) */
+  credentials?: {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+  };
+  /** Cache TTL in seconds (0 = no cache, Phase 4) */
+  cacheTtl?: number;
+  /**
+   * Pre-configured S3 client (for testing or advanced use cases)
+   * If provided, endpoint/region/credentials/profile options are ignored.
+   */
+  client?: S3Client;
+}
+/**
+ * Parsed S3 URI
+ */
+interface ParsedS3Uri {
+  bucket: string;
+  prefix: string;
+}
+//#endregion
+//#region src/s3-afs.d.ts
+/**
+ * AFSS3 Provider using Base Provider pattern
+ *
+ * Provides access to AWS S3 and S3-compatible storage through AFS.
+ * Uses decorator routing (@List, @Read, @Write, @Delete, @Meta, @Actions).
+ *
+ * @example
+ * ```typescript
+ * const s3 = new AFSS3({
+ *   bucket: "my-bucket",
+ *   prefix: "data",
+ *   region: "us-east-1",
+ * });
+ *
+ * // Mount to AFS
+ * afs.mount(s3);
+ *
+ * // List objects
+ * const result = await afs.list("/modules/my-bucket/data");
+ *
+ * // Read object
+ * const content = await afs.read("/modules/my-bucket/data/file.json");
+ * ```
+ */
+declare class AFSS3 extends AFSBaseProvider {
+  readonly name: string;
+  readonly description?: string;
+  readonly accessMode: AFSAccessMode;
+  private options;
+  private client;
+  private listCache?;
+  private statCache?;
+  constructor(options: AFSS3Options);
+  /**
+   * Schema for configuration validation
+   */
+  static schema(): zod0.ZodEffects<zod0.ZodObject<{
+    name: zod0.ZodType<string | undefined, zod0.ZodTypeDef, string | undefined>;
+    description: zod0.ZodType<string | undefined, zod0.ZodTypeDef, string | undefined>;
+    bucket: zod0.ZodString;
+    prefix: zod0.ZodType<string | undefined, zod0.ZodTypeDef, string | undefined>;
+    region: zod0.ZodType<string | undefined, zod0.ZodTypeDef, string | undefined>;
+    accessMode: zod0.ZodType<"readonly" | "readwrite" | undefined, zod0.ZodTypeDef, "readonly" | "readwrite" | undefined>;
+    endpoint: zod0.ZodType<string | undefined, zod0.ZodTypeDef, string | undefined>;
+    forcePathStyle: zod0.ZodType<boolean | undefined, zod0.ZodTypeDef, boolean | undefined>;
+    profile: zod0.ZodType<string | undefined, zod0.ZodTypeDef, string | undefined>;
+    credentials: zod0.ZodType<{
+      accessKeyId: string;
+      secretAccessKey: string;
+      sessionToken?: string | undefined;
+    } | undefined, zod0.ZodTypeDef, {
+      accessKeyId: string;
+      secretAccessKey: string;
+      sessionToken?: string | undefined;
+    } | undefined>;
+    cacheTtl: zod0.ZodType<number | undefined, zod0.ZodTypeDef, number | undefined>;
+  }, "strict", zod0.ZodTypeAny, {
+    bucket: string;
+    name?: string | undefined;
+    description?: string | undefined;
+    prefix?: string | undefined;
+    region?: string | undefined;
+    accessMode?: "readonly" | "readwrite" | undefined;
+    endpoint?: string | undefined;
+    forcePathStyle?: boolean | undefined;
+    profile?: string | undefined;
+    credentials?: {
+      accessKeyId: string;
+      secretAccessKey: string;
+      sessionToken?: string | undefined;
+    } | undefined;
+    cacheTtl?: number | undefined;
+  }, {
+    bucket: string;
+    name?: string | undefined;
+    description?: string | undefined;
+    prefix?: string | undefined;
+    region?: string | undefined;
+    accessMode?: "readonly" | "readwrite" | undefined;
+    endpoint?: string | undefined;
+    forcePathStyle?: boolean | undefined;
+    profile?: string | undefined;
+    credentials?: {
+      accessKeyId: string;
+      secretAccessKey: string;
+      sessionToken?: string | undefined;
+    } | undefined;
+    cacheTtl?: number | undefined;
+  }>, {
+    bucket: string;
+    name?: string | undefined;
+    description?: string | undefined;
+    prefix?: string | undefined;
+    region?: string | undefined;
+    accessMode?: "readonly" | "readwrite" | undefined;
+    endpoint?: string | undefined;
+    forcePathStyle?: boolean | undefined;
+    profile?: string | undefined;
+    credentials?: {
+      accessKeyId: string;
+      secretAccessKey: string;
+      sessionToken?: string | undefined;
+    } | undefined;
+    cacheTtl?: number | undefined;
+  }, any>;
+  /**
+   * Load from configuration file
+   */
+  static load(params: AFSModuleLoadParams): Promise<AFSS3>;
+  /**
+   * Build the full S3 key from a path
+   */
+  private buildS3Key;
+  /**
+   * Generate a unique ID for an S3 object
+   */
+  private generateId;
+  /**
+   * Invalidate caches for a given path
+   */
+  private invalidateCache;
+  /**
+   * Clear all caches
+   */
+  clearCache(): void;
+  listHandler(ctx: RouteContext<{
+    path?: string;
+  }>): Promise<AFSListResult>;
+  /**
+   * List with delimiter (single level)
+   */
+  private listWithDelimiter;
+  listVersionsHandler(ctx: RouteContext<{
+    path: string;
+  }>): Promise<AFSListResult>;
+  readHandler(ctx: RouteContext<{
+    path: string;
+  }>): Promise<AFSEntry>;
+  readVersionHandler(ctx: RouteContext<{
+    path: string;
+    versionId: string;
+  }>): Promise<AFSEntry>;
+  metaHandler(ctx: RouteContext<{
+    path?: string;
+  }>): Promise<AFSEntry>;
+  statHandler(ctx: RouteContext<{
+    path?: string;
+  }>): Promise<AFSStatResult>;
+  writeHandler(ctx: RouteContext<{
+    path: string;
+  }>, payload: AFSWriteEntryPayload): Promise<AFSWriteResult>;
+  deleteHandler(ctx: RouteContext<{
+    path: string;
+  }>): Promise<AFSDeleteResult>;
+  listActionsHandler(ctx: RouteContext<{
+    path: string;
+  }>): Promise<AFSListResult>;
+  selectActionHandler(ctx: RouteContext<{
+    path: string;
+  }>, args: Record<string, unknown>): Promise<AFSExecResult>;
+  presignDownloadActionHandler(ctx: RouteContext<{
+    path: string;
+  }>, args: Record<string, unknown>): Promise<AFSExecResult>;
+  presignUploadActionHandler(ctx: RouteContext<{
+    path: string;
+  }>, args: Record<string, unknown>): Promise<AFSExecResult>;
+  /**
+   * Generate a presigned URL for downloading an object
+   * @deprecated Use action /.actions/presign-download instead
+   */
+  getPresignedDownloadUrl(path: string, options?: {
+    expiresIn?: number;
+  }): Promise<string>;
+  /**
+   * Generate a presigned URL for uploading an object
+   * @deprecated Use action /.actions/presign-upload instead
+   */
+  getPresignedUploadUrl(path: string, options?: {
+    expiresIn?: number;
+    contentType?: string;
+  }): Promise<string>;
+  /**
+   * List all versions of an object
+   * @deprecated Use list on /:path/@versions instead
+   */
+  listVersions(path: string): Promise<Array<{
+    versionId: string;
+    isLatest: boolean;
+    lastModified?: Date;
+    size: number;
+    etag?: string;
+  }>>;
+  /**
+   * Read a specific version of an object
+   * @deprecated Use read on /:path/@versions/:versionId instead
+   */
+  readVersion(path: string, versionId: string): Promise<{
+    content: string;
+    metadata: Record<string, unknown>;
+  }>;
+  /**
+   * Run a SQL-like query on a CSV/JSON/Parquet file (S3 Select)
+   * @deprecated Use action /.actions/select instead
+   */
+  select(path: string, query: string, options?: {
+    inputFormat?: "CSV" | "JSON" | "Parquet";
+    csv?: {
+      fieldDelimiter?: string;
+      recordDelimiter?: string;
+      fileHeaderInfo?: "USE" | "IGNORE" | "NONE";
+    };
+    json?: {
+      type?: "DOCUMENT" | "LINES";
+    };
+  }): Promise<{
+    records: unknown[];
+    stats?: {
+      bytesScanned: number;
+      bytesProcessed: number;
+      bytesReturned: number;
+    };
+  }>;
+  /**
+   * Create a directory marker
+   * @deprecated Use write with empty content instead
+   */
+  mkdir(path: string): Promise<void>;
+}
+//#endregion
+export { AFSS3, type AFSS3Options, type ParsedS3Uri };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/s3-afs.ts"],"mappings":"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"}