@_linked/s3 1.0.2

package/.changeset/README.md

@@ -0,0 +1,20 @@
+# Changesets
+
+This package uses [changesets](https://github.com/changesets/changesets) for version management and publishing.
+
+## Adding a changeset
+
+When making a change that should trigger a new release, run:
+
+```bash
+npx changeset
+```
+
+This generates a markdown file in `.changeset/` describing the change. Commit it with your PR.
+
+On merge to `main`, the publish workflow either:
+
+1. Creates (or updates) a **Release PR** that bumps the version + updates `CHANGELOG.md`, or
+2. If the Release PR is already merged, publishes the new version to npm.
+
+Changes that don't need a release (docs, CI config, tooling) can skip the changeset — the check is a warning, not a block.

package/.changeset/config.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": [
+    "@changesets/changelog-github",
+    { "repo": "linked-cm/s3" }
+  ],
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

package/.github/workflows/changeset-check.yml

@@ -0,0 +1,44 @@
+name: Changeset Check
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  changeset-check:
+    name: Check for changeset
+    # Skip the check on the automated Release PR.
+    if: ${{ github.head_ref != 'changeset-release/main' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Check for changeset files
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const { data: files } = await github.rest.pulls.listFiles({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.issue.number,
+            });
+
+            const hasChangeset = files.some(f =>
+              f.filename.startsWith('.changeset/') &&
+              f.filename.endsWith('.md') &&
+              f.filename !== '.changeset/README.md'
+            );
+
+            if (!hasChangeset) {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: "No changeset found. If this PR should trigger a release, run `npx changeset` and commit the generated file.\n\nIf this change doesn't need a release (docs, CI config, etc.), you can ignore this message."
+              });
+              core.warning('No changeset file found in this PR.');
+            }

package/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  build-and-test:
+    name: Build & Test
+    # Skip CI on the automated Release PR created by changesets/action.
+    if: ${{ !(github.event.pull_request.base.ref == 'main' && github.head_ref == 'changeset-release/main') }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.16.0
+
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Build
+        run: npm run build
+
+      - name: Test
+        run: npm test --if-present

package/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    name: Publish Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22.16.0
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: npm ci --legacy-peer-deps
+
+      - name: Build
+        run: npm run build
+
+      - name: Create release Pull Request or Publish
+        uses: changesets/action@v1
+        with:
+          publish: npx changeset publish
+          title: 'chore: release'
+          commit: 'chore: release'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @\_linked/s3
+
+## 1.0.2
+
+### Patch Changes
+
+- [`2a8c5d8`](https://github.com/linked-cm/s3/commit/2a8c5d8288f43270eb666a2a4c6ec745791ecb66) - Initial release under the new publishing setup.

package/README.md

@@ -0,0 +1,60 @@
+# lincd-s3
+
+A plug-n-play solution for using an S3 Bucket in LINCD.
+
+In place of your usual backend store, you can use the following to get started with S3:
+
+```ts
+// ...
+const {
+  LinkedFileStorage,
+} = require('@_linked/core/lib/utils/LinkedFileStorage');
+const { LinkedStorage } = require('@_linked/core/lib/utils/LinkedStorage');
+const { S3QuadStore } = require('lincd-s3/lib/shapes/S3QuadStore');
+const { S3FileStore } = require('lincd-s3/lib/shapes/S3FileStore');
+
+// This translates to be the Object name in the bucket. If no object
+// is found with this name, then one will be created - just like how a
+// regular NodeFileStore works!
+const QUADSTORE_NAME = 'foo-bar-data';
+const s3Quads = new S3QuadStore(QUADSTORE_NAME);
+
+LinkedStorage.setDefaultStore(s3Quads);
+
+// Set up an S3 Filestore
+const FILESTORE_NAME = 'baz-qux-files';
+const s3Files = new S3FileStore(FILESTORE_NAME);
+
+LinkedFileStorage.setDefaultStore(s3Files);
+// ...
+```
+
+## Environment Variables
+
+Unless stated otherwise, the following environment variables are required:
+
+```properties
+# Generated using whatever service is hosting your bucket
+AWS_ACCESS_KEY_ID=ABC123XYZ789
+AWS_SECRET_ACCESS_KEY=aBc123Def456xYz789
+
+# The endpoint on which your bucket resides. It's important to note that
+# this is the HOST address of your bucket - i.e. it SHOULDN'T contain
+# your bucket name!!
+S3_BUCKET_ENDPOINT=https://my.bucket-provider.com
+
+# The name of your buckets
+S3_FILES_BUCKET_NAME=my-file-bucket
+S3_QUADS_BUCKET_NAME=my-data-bucket
+
+# OPTIONAL: If using a CDN, you can specify the URL here and it will be used
+S3_CDN_URL=https://my.cdn-provider.com
+```
+
+The S3 client will automagically form the correct URL for your bucket - in this case it would
+be https://my-data-bucket.my.bucket-provider.com or https://my-file-bucket.my.bucket-provider.com
+
+## See also:
+
+- [lincd-filebase](https://www.npmjs.com/package/lincd-filebase) - An implementation
+  for [filebase](https://filebase.com) IPFS bucket storage

package/lib/cjs/data/s3.json

@@ -0,0 +1,20 @@
+{
+  "@context": {
+    "dc": "http://purl.org/dc/elements/1.1/",
+    "owl": "http://www.w3.org/2002/07/owl#",
+    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
+    "s3": "http://lincd.org/ont/s3/"
+  },
+  "@graph": [
+    {
+      "@id": "s3:ExampleClass",
+      "@type": "rdfs:Class",
+      "rdfs:comment": "This is an example class. You can remove or rename it",
+      "rdfs:isDefinedBy": {
+        "@id": "s3:"
+      },
+      "rdfs:label": "Example Class"
+    }
+  ]
+}

package/lib/cjs/index.d.ts

@@ -0,0 +1,5 @@
+import './types.js';
+import './ontologies/s3.js';
+import './shapes/S3Bucket.js';
+import './shapes/S3FileStore.js';
+import './utils/accessUrl.js';

package/lib/cjs/ontologies/s3.d.ts

@@ -0,0 +1,38 @@
+export declare var loadData: () => Promise<{
+    "@context": {
+        dc: string;
+        owl: string;
+        rdf: string;
+        rdfs: string;
+        s3: string;
+    };
+    "@graph": {
+        "@id": string;
+        "@type": string;
+        "rdfs:comment": string;
+        "rdfs:isDefinedBy": {
+            "@id": string;
+        };
+        "rdfs:label": string;
+    }[];
+}>;
+export declare var ns: (term: string) => import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare var _self: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare var Bucket: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare var FileStore: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare var FrontendStore: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare var QuadStore: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare var bucket: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare var endpoint: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare var key: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare var secret: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare const s3: {
+    Bucket: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+    FileStore: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+    FrontendStore: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+    QuadStore: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+    bucket: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+    endpoint: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+    key: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+    secret: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+};

package/lib/cjs/package.d.ts

@@ -0,0 +1,4 @@
+export declare const linkedShape: {
+    <T extends typeof import("@_linked/core/shapes/Shape").Shape>(constructor: T): void;
+    <T extends typeof import("@_linked/core/shapes/Shape").Shape>(config?: import("@_linked/core/utils/Package").ShapeConfig): (constructor: T) => void;
+}, linkedUtil: (constructor: any) => any, linkedOntology: (allFileExports: any, nameSpace: (term: string) => import("@_linked/core/utils/NodeReference").NodeReferenceValue, suggestedPrefixAndFileName: string, loadDataFunction?: () => Promise<any>, dataSource?: string | string[]) => void, registerPackageExport: (exportedObject: any) => void, packageExports: any, packageName: string;

package/lib/cjs/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@_linked/s3",
+  "displayName": "s3",
+  "description": "A general purpose Simple Storage Service (S3) package to be extended or used as is",
+  "author": {
+    "name": "Valentine Wilson",
+    "email": "valentine@semantu.com",
+    "url": "https://vw.codes"
+  },
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "version": "1.0.2",
+  "linkedPackage": true,
+  "license": "ISC",
+  "scripts": {
+    "start": "npm exec linked dev",
+    "build": "yarn linked build",
+    "prepublishOnly": "yarn linked build production",
+    "postpublish": "npm exec linked register"
+  },
+  "keywords": [
+    "lincd",
+    "linked data",
+    "interoperable",
+    "semantic web",
+    "web3",
+    "s3",
+    "simple storage service",
+    "cloud storage",
+    "aws"
+  ],
+  "dependencies": {
+    "@_linked/core": "^2.2.1",
+    "@_linked/server": "~1.0",
+    "@_linked/server-utils": "~1.0",
+    "@aws-sdk/client-s3": "^3.159.0",
+    "@aws-sdk/credential-providers": "^3.159.0",
+    "cron": "^3.1.7",
+    "mime": "2.6.0"
+  },
+  "devDependencies": {
+    "@_linked/cli": "^1.2",
+    "@types/mime": "^3.0.4",
+    "tsconfig-to-dual-package": "^1.2.0",
+    "typescript": "^5.7.3",
+    "typescript-plugin-css-modules": "^5.1.0",
+    "@changesets/cli": "^2.29.8",
+    "@changesets/changelog-github": "^0.5.2"
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "lib/esm/*"
+      ]
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "commonjs"
+}

package/lib/cjs/shapes/S3Bucket.d.ts

@@ -0,0 +1,80 @@
+import { DeleteObjectCommandInput, S3Client } from '@aws-sdk/client-s3';
+import { PutObjectCommandInput, PutObjectCommandOutput } from '@aws-sdk/client-s3/dist-types/commands/PutObjectCommand';
+import { StreamingBlobPayloadInputTypes } from '@smithy/types';
+import { Shape } from '@_linked/core/shapes/Shape';
+export interface S3ClientConfigInput {
+    endpoint?: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    region?: string;
+}
+export declare const endpoint: string;
+/**
+ * Builds an S3 client from explicit config, falling back to legacy env vars.
+ * This enables multiple S3 stores in one process with independent credentials/endpoints.
+ */
+export declare const createS3Client: (config?: S3ClientConfigInput) => S3Client;
+/**
+ * Legacy singleton exported for backward compatibility. New code should prefer
+ * per-instance clients by passing config into S3Bucket/S3FileStore.
+ */
+export declare const s3Client: S3Client;
+export declare class S3Bucket extends Shape {
+    static targetClass: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+    protected _client: S3Client;
+    label: string;
+    private ensureKeyPromise;
+    constructor(n?: string | {
+        id: string;
+    }, clientConfig?: S3ClientConfigInput);
+    get endpoint(): string;
+    /**
+     * Delete an object from the bucket.
+     * @param key The key of the object to delete
+     * @param options Additional options to pass to the DeleteObjectCommand
+     * @returns The response from the DeleteObjectCommand
+     * @todo Batch delete, see https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html
+     */
+    deleteObject(key: string, options?: Omit<DeleteObjectCommandInput, 'Key' | 'Bucket'>): Promise<import("@aws-sdk/client-s3").DeleteObjectCommandOutput>;
+    copyObject(sourceKey: string, destinationKey: string, options?: Omit<PutObjectCommandInput, 'Key' | 'Bucket'>): Promise<boolean>;
+    /**
+     * Put an object into the bucket.
+     *
+     * @param key The key of the object to PUT (i.e. file name)
+     * @param value The value of the object to PUT (i.e. file contents)
+     * @param options Additional options to pass to the PutObjectCommand
+     * @returns The response from the PutObjectCommand
+     */
+    putObject(key: string, value: StreamingBlobPayloadInputTypes, options?: Omit<PutObjectCommandInput, 'Body' | 'Key' | 'Bucket'>): Promise<PutObjectCommandOutput>;
+    /**
+     * Get a list of all object keys in the bucket.
+     * Important to note that only a maximum 1000 keys will be returned.
+     *
+     * @param prefix The prefix to search for in the bucket. This can be a folder or the beginning of a file name.
+     * @returns A list of all object keys in the bucket
+     * @todo Recursive search within directories
+     * @todo Implement pagination
+     */
+    getAllObjectKeys(prefix?: string): Promise<string[]>;
+    /**
+     * Get the contents of an object in the bucket.
+     * @param key The key of the object to get
+     * @returns The contents of the object as a string
+     */
+    getObject(key: string): Promise<string>;
+    /**
+     * Ensure that the given key exists in the bucket, the file contents
+     * will be an empty json object.
+     *
+     * @param key The key to insert if it does not exist
+     * @returns The promise that will resolve when the key exists
+     */
+    ensureKeyExists(key: string): Promise<string | void>;
+    private _ensureKeyExists;
+    private keyExists;
+    /**
+     * Create the bucket if it does not exist.
+     * @returns The promise that will resolve when the bucket exists
+     */
+    createBucket(): Promise<import("@aws-sdk/client-s3").CreateBucketCommandOutput>;
+}

package/lib/cjs/shapes/S3FileStore.d.ts

@@ -0,0 +1,59 @@
+import { IFileStore } from '@_linked/core/interfaces/IFileStore';
+import { Shape } from '@_linked/core/shapes/Shape';
+import { type S3ClientConfigInput } from './S3Bucket.js';
+import type { Readable } from 'stream';
+export interface S3FileStoreConfig {
+    bucketName?: string;
+    accessURL?: string;
+    prefix?: string;
+    clientConfig?: S3ClientConfigInput;
+}
+export declare class S3FileStore extends Shape implements IFileStore {
+    static targetClass: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+    label: string;
+    private _bucket;
+    private readonly config;
+    readonly accessURL: string;
+    constructor(n: string | {
+        id: string;
+    }, config?: S3FileStoreConfig);
+    private get bucket();
+    private resolveBucketName;
+    private resolveAccessURL;
+    private get prefix();
+    private normalizePath;
+    private applyPrefix;
+    private stripPrefix;
+    /**
+     * List all files in the bucket
+     * @param recursive Whether to list files recursively or just the top-level files
+     * @returns A list of file paths, relative to the endpoint
+     * @todo Think about taking an options parameter instead of positional args
+     * @todo Take a path parameter to list files in a subdirectory
+     */
+    listFiles(prefix?: string): Promise<string[]>;
+    /**
+     * Save a file to the bucket
+     * @param filePath The path to save the file to, relative to the endpoint
+     * @param fileContent The contents of the file as a buffer
+     * @returns The public URL of the file
+     */
+    saveFile(filePath: string, fileContent: string | Uint8Array | Buffer | Readable, mimeType?: string, preventDuplicate?: boolean): Promise<string>;
+    /**
+     * Get a file from the bucket
+     * @param filePath The path of the file to get, relative to the endpoint
+     * @returns The contents of the file as a buffer
+     */
+    getFile(filePath: string): Promise<Buffer | null>;
+    /**
+     * Delete a file from the bucket
+     * @param filePath The path of the file to delete, relative to the endpoint
+     */
+    deleteFile(filePath: string): Promise<void>;
+    /**
+     * Check if a file exists in the bucket
+     * @param filePath The path of the file to check, relative to the endpoint
+     * @returns Whether the file exists
+     */
+    fileExists(filePath: string): Promise<boolean>;
+}

package/lib/cjs/types.d.ts

@@ -0,0 +1,12 @@
+declare module '*.module.css' {
+    const classes: {
+        [key: string]: string;
+    };
+    export default classes;
+}
+declare module '*.module.scss' {
+    const classes: {
+        [key: string]: string;
+    };
+    export default classes;
+}

package/lib/cjs/utils/accessUrl.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Access URL for user-uploaded files. This intentionally prefers upload-specific
+ * env vars, then falls back to legacy shared env vars.
+ */
+export declare const getAccessURLUploadsStore: () => string;
+/**
+ * Access URL for static web assets (bundles/images/root). This can be independent
+ * from uploads and is expected to include the release version when configured by
+ * app storage bootstrap (for example ".../4.1.1").
+ */
+export declare const getAccessURLStaticStore: () => string;
+/**
+ * Backward-compatible alias for existing imports.
+ */
+export declare const getAccessURLS3FileStore: () => string;

package/lib/esm/data/s3.json

@@ -0,0 +1,20 @@
+{
+  "@context": {
+    "dc": "http://purl.org/dc/elements/1.1/",
+    "owl": "http://www.w3.org/2002/07/owl#",
+    "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
+    "s3": "http://lincd.org/ont/s3/"
+  },
+  "@graph": [
+    {
+      "@id": "s3:ExampleClass",
+      "@type": "rdfs:Class",
+      "rdfs:comment": "This is an example class. You can remove or rename it",
+      "rdfs:isDefinedBy": {
+        "@id": "s3:"
+      },
+      "rdfs:label": "Example Class"
+    }
+  ]
+}

package/lib/esm/index.d.ts

@@ -0,0 +1,5 @@
+import './types.js';
+import './ontologies/s3.js';
+import './shapes/S3Bucket.js';
+import './shapes/S3FileStore.js';
+import './utils/accessUrl.js';

package/lib/esm/ontologies/s3.d.ts

@@ -0,0 +1,38 @@
+export declare var loadData: () => Promise<{
+    "@context": {
+        dc: string;
+        owl: string;
+        rdf: string;
+        rdfs: string;
+        s3: string;
+    };
+    "@graph": {
+        "@id": string;
+        "@type": string;
+        "rdfs:comment": string;
+        "rdfs:isDefinedBy": {
+            "@id": string;
+        };
+        "rdfs:label": string;
+    }[];
+}>;
+export declare var ns: (term: string) => import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare var _self: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare var Bucket: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare var FileStore: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare var FrontendStore: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare var QuadStore: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare var bucket: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare var endpoint: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare var key: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare var secret: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+export declare const s3: {
+    Bucket: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+    FileStore: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+    FrontendStore: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+    QuadStore: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+    bucket: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+    endpoint: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+    key: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+    secret: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+};

package/lib/esm/package.d.ts

@@ -0,0 +1,4 @@
+export declare const linkedShape: {
+    <T extends typeof import("@_linked/core/shapes/Shape").Shape>(constructor: T): void;
+    <T extends typeof import("@_linked/core/shapes/Shape").Shape>(config?: import("@_linked/core/utils/Package").ShapeConfig): (constructor: T) => void;
+}, linkedUtil: (constructor: any) => any, linkedOntology: (allFileExports: any, nameSpace: (term: string) => import("@_linked/core/utils/NodeReference").NodeReferenceValue, suggestedPrefixAndFileName: string, loadDataFunction?: () => Promise<any>, dataSource?: string | string[]) => void, registerPackageExport: (exportedObject: any) => void, packageExports: any, packageName: string;

package/lib/esm/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@_linked/s3",
+  "displayName": "s3",
+  "description": "A general purpose Simple Storage Service (S3) package to be extended or used as is",
+  "author": {
+    "name": "Valentine Wilson",
+    "email": "valentine@semantu.com",
+    "url": "https://vw.codes"
+  },
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "version": "1.0.2",
+  "linkedPackage": true,
+  "license": "ISC",
+  "scripts": {
+    "start": "npm exec linked dev",
+    "build": "yarn linked build",
+    "prepublishOnly": "yarn linked build production",
+    "postpublish": "npm exec linked register"
+  },
+  "keywords": [
+    "lincd",
+    "linked data",
+    "interoperable",
+    "semantic web",
+    "web3",
+    "s3",
+    "simple storage service",
+    "cloud storage",
+    "aws"
+  ],
+  "dependencies": {
+    "@_linked/core": "^2.2.1",
+    "@_linked/server": "~1.0",
+    "@_linked/server-utils": "~1.0",
+    "@aws-sdk/client-s3": "^3.159.0",
+    "@aws-sdk/credential-providers": "^3.159.0",
+    "cron": "^3.1.7",
+    "mime": "2.6.0"
+  },
+  "devDependencies": {
+    "@_linked/cli": "^1.2",
+    "@types/mime": "^3.0.4",
+    "tsconfig-to-dual-package": "^1.2.0",
+    "typescript": "^5.7.3",
+    "typescript-plugin-css-modules": "^5.1.0",
+    "@changesets/cli": "^2.29.8",
+    "@changesets/changelog-github": "^0.5.2"
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "lib/esm/*"
+      ]
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module"
+}

package/lib/esm/shapes/S3Bucket.d.ts

@@ -0,0 +1,80 @@
+import { DeleteObjectCommandInput, S3Client } from '@aws-sdk/client-s3';
+import { PutObjectCommandInput, PutObjectCommandOutput } from '@aws-sdk/client-s3/dist-types/commands/PutObjectCommand';
+import { StreamingBlobPayloadInputTypes } from '@smithy/types';
+import { Shape } from '@_linked/core/shapes/Shape';
+export interface S3ClientConfigInput {
+    endpoint?: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    region?: string;
+}
+export declare const endpoint: string;
+/**
+ * Builds an S3 client from explicit config, falling back to legacy env vars.
+ * This enables multiple S3 stores in one process with independent credentials/endpoints.
+ */
+export declare const createS3Client: (config?: S3ClientConfigInput) => S3Client;
+/**
+ * Legacy singleton exported for backward compatibility. New code should prefer
+ * per-instance clients by passing config into S3Bucket/S3FileStore.
+ */
+export declare const s3Client: S3Client;
+export declare class S3Bucket extends Shape {
+    static targetClass: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+    protected _client: S3Client;
+    label: string;
+    private ensureKeyPromise;
+    constructor(n?: string | {
+        id: string;
+    }, clientConfig?: S3ClientConfigInput);
+    get endpoint(): string;
+    /**
+     * Delete an object from the bucket.
+     * @param key The key of the object to delete
+     * @param options Additional options to pass to the DeleteObjectCommand
+     * @returns The response from the DeleteObjectCommand
+     * @todo Batch delete, see https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteObjects.html
+     */
+    deleteObject(key: string, options?: Omit<DeleteObjectCommandInput, 'Key' | 'Bucket'>): Promise<import("@aws-sdk/client-s3").DeleteObjectCommandOutput>;
+    copyObject(sourceKey: string, destinationKey: string, options?: Omit<PutObjectCommandInput, 'Key' | 'Bucket'>): Promise<boolean>;
+    /**
+     * Put an object into the bucket.
+     *
+     * @param key The key of the object to PUT (i.e. file name)
+     * @param value The value of the object to PUT (i.e. file contents)
+     * @param options Additional options to pass to the PutObjectCommand
+     * @returns The response from the PutObjectCommand
+     */
+    putObject(key: string, value: StreamingBlobPayloadInputTypes, options?: Omit<PutObjectCommandInput, 'Body' | 'Key' | 'Bucket'>): Promise<PutObjectCommandOutput>;
+    /**
+     * Get a list of all object keys in the bucket.
+     * Important to note that only a maximum 1000 keys will be returned.
+     *
+     * @param prefix The prefix to search for in the bucket. This can be a folder or the beginning of a file name.
+     * @returns A list of all object keys in the bucket
+     * @todo Recursive search within directories
+     * @todo Implement pagination
+     */
+    getAllObjectKeys(prefix?: string): Promise<string[]>;
+    /**
+     * Get the contents of an object in the bucket.
+     * @param key The key of the object to get
+     * @returns The contents of the object as a string
+     */
+    getObject(key: string): Promise<string>;
+    /**
+     * Ensure that the given key exists in the bucket, the file contents
+     * will be an empty json object.
+     *
+     * @param key The key to insert if it does not exist
+     * @returns The promise that will resolve when the key exists
+     */
+    ensureKeyExists(key: string): Promise<string | void>;
+    private _ensureKeyExists;
+    private keyExists;
+    /**
+     * Create the bucket if it does not exist.
+     * @returns The promise that will resolve when the bucket exists
+     */
+    createBucket(): Promise<import("@aws-sdk/client-s3").CreateBucketCommandOutput>;
+}

package/lib/esm/shapes/S3FileStore.d.ts

@@ -0,0 +1,59 @@
+import { IFileStore } from '@_linked/core/interfaces/IFileStore';
+import { Shape } from '@_linked/core/shapes/Shape';
+import { type S3ClientConfigInput } from './S3Bucket.js';
+import type { Readable } from 'stream';
+export interface S3FileStoreConfig {
+    bucketName?: string;
+    accessURL?: string;
+    prefix?: string;
+    clientConfig?: S3ClientConfigInput;
+}
+export declare class S3FileStore extends Shape implements IFileStore {
+    static targetClass: import("@_linked/core/utils/NodeReference.js").NodeReferenceValue;
+    label: string;
+    private _bucket;
+    private readonly config;
+    readonly accessURL: string;
+    constructor(n: string | {
+        id: string;
+    }, config?: S3FileStoreConfig);
+    private get bucket();
+    private resolveBucketName;
+    private resolveAccessURL;
+    private get prefix();
+    private normalizePath;
+    private applyPrefix;
+    private stripPrefix;
+    /**
+     * List all files in the bucket
+     * @param recursive Whether to list files recursively or just the top-level files
+     * @returns A list of file paths, relative to the endpoint
+     * @todo Think about taking an options parameter instead of positional args
+     * @todo Take a path parameter to list files in a subdirectory
+     */
+    listFiles(prefix?: string): Promise<string[]>;
+    /**
+     * Save a file to the bucket
+     * @param filePath The path to save the file to, relative to the endpoint
+     * @param fileContent The contents of the file as a buffer
+     * @returns The public URL of the file
+     */
+    saveFile(filePath: string, fileContent: string | Uint8Array | Buffer | Readable, mimeType?: string, preventDuplicate?: boolean): Promise<string>;
+    /**
+     * Get a file from the bucket
+     * @param filePath The path of the file to get, relative to the endpoint
+     * @returns The contents of the file as a buffer
+     */
+    getFile(filePath: string): Promise<Buffer | null>;
+    /**
+     * Delete a file from the bucket
+     * @param filePath The path of the file to delete, relative to the endpoint
+     */
+    deleteFile(filePath: string): Promise<void>;
+    /**
+     * Check if a file exists in the bucket
+     * @param filePath The path of the file to check, relative to the endpoint
+     * @returns Whether the file exists
+     */
+    fileExists(filePath: string): Promise<boolean>;
+}

package/lib/esm/types.d.ts

@@ -0,0 +1,12 @@
+declare module '*.module.css' {
+    const classes: {
+        [key: string]: string;
+    };
+    export default classes;
+}
+declare module '*.module.scss' {
+    const classes: {
+        [key: string]: string;
+    };
+    export default classes;
+}

package/lib/esm/utils/accessUrl.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Access URL for user-uploaded files. This intentionally prefers upload-specific
+ * env vars, then falls back to legacy shared env vars.
+ */
+export declare const getAccessURLUploadsStore: () => string;
+/**
+ * Access URL for static web assets (bundles/images/root). This can be independent
+ * from uploads and is expected to include the release version when configured by
+ * app storage bootstrap (for example ".../4.1.1").
+ */
+export declare const getAccessURLStaticStore: () => string;
+/**
+ * Backward-compatible alias for existing imports.
+ */
+export declare const getAccessURLS3FileStore: () => string;

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@_linked/s3",
+  "displayName": "s3",
+  "description": "A general purpose Simple Storage Service (S3) package to be extended or used as is",
+  "author": {
+    "name": "Valentine Wilson",
+    "email": "valentine@semantu.com",
+    "url": "https://vw.codes"
+  },
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "version": "1.0.2",
+  "linkedPackage": true,
+  "main": "lib/cjs/index.js",
+  "types": "dist/s3.d.ts",
+  "license": "ISC",
+  "scripts": {
+    "start": "npm exec linked dev",
+    "build": "yarn linked build",
+    "prepublishOnly": "yarn linked build production",
+    "postpublish": "npm exec linked register"
+  },
+  "keywords": [
+    "lincd",
+    "linked data",
+    "interoperable",
+    "semantic web",
+    "web3",
+    "s3",
+    "simple storage service",
+    "cloud storage",
+    "aws"
+  ],
+  "dependencies": {
+    "@_linked/core": "^2.2.1",
+    "@_linked/server": "~1.0",
+    "@_linked/server-utils": "~1.0",
+    "@aws-sdk/client-s3": "^3.159.0",
+    "@aws-sdk/credential-providers": "^3.159.0",
+    "cron": "^3.1.7",
+    "mime": "2.6.0"
+  },
+  "devDependencies": {
+    "@_linked/cli": "^1.2",
+    "@types/mime": "^3.0.4",
+    "tsconfig-to-dual-package": "^1.2.0",
+    "typescript": "^5.7.3",
+    "typescript-plugin-css-modules": "^5.1.0",
+    "@changesets/cli": "^2.29.8",
+    "@changesets/changelog-github": "^0.5.2"
+  },
+  "module": "lib/esm/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/esm/index.d.ts",
+      "import": "./lib/esm/index.js",
+      "require": "./lib/cjs/index.js"
+    },
+    "./*.js": {
+      "types": "./lib/esm/*.d.ts",
+      "import": "./lib/esm/*.js",
+      "require": "./lib/cjs/*.js"
+    },
+    "./*": {
+      "types": "./lib/esm/*.d.ts",
+      "import": "./lib/esm/*.js",
+      "require": "./lib/cjs/*.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "lib/esm/*"
+      ]
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/tsconfig-cjs.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "es6",
+    "outDir": "lib/cjs"
+  }
+}

package/tsconfig-esm.json

@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "esnext",
+    "target": "es2018",
+    "outDir": "lib/esm",
+    "moduleResolution": "node"
+  }
+}