{
  "$meta": {
    "package": "@walkeros/server-store-s3",
    "version": "4.2.1",
    "type": "store",
    "platform": [
      "server"
    ],
    "docs": "https://www.walkeros.io/docs/stores/server/s3",
    "source": "https://github.com/elbwalker/walkerOS/tree/main/packages/server/stores/s3/src"
  },
  "schemas": {
    "settings": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "properties": {
        "bucket": {
          "type": "string",
          "minLength": 1,
          "description": "S3 bucket name"
        },
        "endpoint": {
          "type": "string",
          "format": "uri",
          "description": "S3-compatible endpoint URL (like https://s3.eu-west-1.amazonaws.com)"
        },
        "accessKeyId": {
          "type": "string",
          "minLength": 1,
          "description": "S3 access key ID"
        },
        "secretAccessKey": {
          "type": "string",
          "minLength": 1,
          "description": "S3 secret access key"
        },
        "region": {
          "default": "auto",
          "description": "AWS region for SigV4 signing",
          "type": "string"
        },
        "prefix": {
          "description": "Key prefix prepended to all store keys for scoping",
          "type": "string"
        }
      },
      "required": [
        "bucket",
        "endpoint",
        "accessKeyId",
        "secretAccessKey"
      ],
      "additionalProperties": false
    },
    "setup": {
      "$schema": "http://json-schema.org/draft-07/schema#",
      "type": "object",
      "properties": {
        "region": {
          "default": "eu-central-1",
          "description": "Region the bucket is created in. Defaults to settings.region when concrete (not \"auto\"), otherwise eu-central-1.",
          "type": "string"
        }
      },
      "required": [],
      "additionalProperties": false,
      "description": "Provisioning options for \"walkeros setup store.<id>\". Idempotent: only the bucket is created. Encryption, public-access block, versioning, lifecycle rules, and tags are not applied here (s3mini does not expose those operations); configure them once via the AWS Console or \"aws s3api\"."
    }
  },
  "examples": {
    "awsAssets": {
      "settings": {
        "bucket": "my-assets",
        "endpoint": "https://s3.eu-west-1.amazonaws.com",
        "accessKeyId": "$env.S3_ACCESS_KEY",
        "secretAccessKey": "$env.S3_SECRET_KEY",
        "region": "eu-west-1",
        "prefix": "public"
      },
      "file": true
    },
    "r2Bucket": {
      "settings": {
        "bucket": "my-bucket",
        "endpoint": "https://ACCOUNT_ID.r2.cloudflarestorage.com",
        "accessKeyId": "$env.R2_ACCESS_KEY",
        "secretAccessKey": "$env.R2_SECRET_KEY"
      },
      "file": true
    },
    "step": {
      "prefixScoping": {
        "title": "Prefix scoping",
        "description": "Key \"walker.js\" with prefix \"public/\" resolves to S3 path \"public/walker.js\"",
        "in": {
          "operation": "get",
          "key": "walker.js",
          "settings": {
            "bucket": "my-assets",
            "prefix": "public"
          }
        },
        "out": [
          [
            "get",
            "public/walker.js",
            "Bytes<...>"
          ]
        ]
      },
      "readAwsS3": {
        "title": "Read from S3",
        "description": "Read object from S3 and receive its raw bytes byte-exact",
        "in": {
          "operation": "get",
          "key": "walker.js"
        },
        "out": [
          [
            "get",
            "walker.js",
            "Bytes<(function(){...})()>"
          ]
        ]
      }
    },
    "structuredKv": {
      "settings": {
        "bucket": "my-state",
        "endpoint": "https://s3.eu-west-1.amazonaws.com",
        "accessKeyId": "$env.S3_ACCESS_KEY",
        "secretAccessKey": "$env.S3_SECRET_KEY",
        "region": "eu-west-1"
      }
    }
  },
  "hints": {
    "file-mode": {
      "text": "Default mode is structured: values are StoreValue data round-tripped through the shared core codec and stored with Content-Type application/json, good for session state, lookups, and cached responses. Set config.file: true to persist raw bytes byte-exact with the real mime derived from the key (set accepts Uint8Array or string), the mode for serving assets such as walker.js via the file transformer. One store instance is exactly one mode. Do not pair file: true with a cache; the cache wraps structured stores and flow_validate flags the combination."
    }
  }
}