@plasius/storage 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on **[Keep a Changelog](https://keepachangelog.com/en/1.1.0/)**, and this project adheres to **[Semantic Versioning](https://semver.org/spec/v2.0.0.html)**.
+
+---
+
+## [Unreleased]
+
+- **Added**
+  - (placeholder)
+
+- **Changed**
+  - (placeholder)
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+
+## [1.0.0] - 2026-02-12
+
+- **Added**
+  - Standalone public package scaffold at repository root with independent CI/CD, ADRs, and legal governance assets.
+
+- **Changed**
+  - Add dual ESM + CJS build outputs with `exports` entries and CJS artifacts in `dist-cjs/`.
+
+- **Fixed**
+  - Removed monorepo-relative TypeScript configuration coupling for standalone builds.
+
+- **Security**
+  - Added baseline public package governance and CLA documentation.
+
+---
+
+## Release process (maintainers)
+
+1. Update `CHANGELOG.md` under **Unreleased** with user-visible changes.
+2. Bump version in `package.json` following SemVer (major/minor/patch).
+3. Move entries from **Unreleased** to a new version section with the current date.
+4. Tag the release in Git (`vX.Y.Z`) and push tags.
+5. Publish to npm (via CI/CD or `npm publish`).
+
+> Tip: Use Conventional Commits in PR titles/bodies to make changelog updates easier.
+
+---
+
+[Unreleased]: https://github.com/Plasius-LTD/storage/compare/v1.0.0...HEAD
+
+## [1.0.0] - 2026-02-11
+
+- **Added**
+  - Initial release.
+
+- **Changed**
+  - (placeholder)
+
+- **Fixed**
+  - (placeholder)
+
+- **Security**
+  - (placeholder)
+[1.0.0]: https://github.com/Plasius-LTD/storage/releases/tag/v1.0.0

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,79 @@
+# Contributor Covenant Code of Conduct v2.1
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others’ private information, such as a physical or email address, without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at [conduct@plasius.co.uk](mailto:conduct@plasius.co.uk). All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Enforcement Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact:** Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence:** A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact:** A violation through a single incident or series of actions.
+
+**Consequence:** A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact:** A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence:** A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact:** Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence:** A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html)
+
+For answers to common questions about this code of conduct, see the [FAQ](https://www.contributor-covenant.org/faq)
+
+[homepage]: [https://www.contributor-covenant.org](https://www.contributor-covenant.org)
+
+If you have any questions or concerns regarding this Code of Conduct, please contact us at [conduct@plasius.co.uk](mailto:conduct@plasius.co.uk).

package/CONTRIBUTORS.md

@@ -0,0 +1,27 @@
+# Contributing Guidelines
+
+Thank you for considering contributing to this project! We welcome contributions that improve the code, documentation, and overall project quality.
+
+## Getting Started
+
+- Fork the repository.
+- Create a feature branch from `main`.
+- Commit your changes with clear messages (we follow **Conventional Commits**).
+- Push your branch and open a Pull Request (PR).
+
+## Requirements
+
+- Write tests alongside code where possible.
+- Ensure all tests pass before submitting a PR.
+- Follow the repository’s coding style and linting rules.
+- Update documentation (README, ADRs, etc.) when making significant changes.
+- When making architectural changes, create a new ADR (Architecture Decision Record) that **succeeds** the previous one rather than modifying old ADRs. This preserves history and ensures decisions are traceable.
+- Use the [ADR template](./docs/adrs/adr-template.md) when writing new ADRs to ensure consistency.
+- Before your first contribution, sign the appropriate Contributor License Agreement (CLA). See [legal/CLA.md](legal/CLA.md) for details, then email the signed document to [contributors@plasius.co.uk](mailto:contributors@plasius.co.uk).
+
+## Communication
+
+- Use GitHub Issues for bugs and feature requests.
+- Pull Requests should describe the problem, solution, and trade-offs.
+
+We appreciate your support in making this project better!

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Plasius LTD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @plasius/storage
+
+[![npm version](https://img.shields.io/npm/v/@plasius/storage.svg)](https://www.npmjs.com/package/@plasius/storage)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/Plasius-LTD/storage/ci.yml?branch=main&label=build&style=flat)](https://github.com/Plasius-LTD/storage/actions/workflows/ci.yml)
+[![coverage](https://img.shields.io/codecov/c/github/Plasius-LTD/storage)](https://codecov.io/gh/Plasius-LTD/storage)
+[![License](https://img.shields.io/github/license/Plasius-LTD/storage)](./LICENSE)
+[![Code of Conduct](https://img.shields.io/badge/code%20of%20conduct-yes-blue.svg)](./CODE_OF_CONDUCT.md)
+[![Security Policy](https://img.shields.io/badge/security%20policy-yes-orange.svg)](./SECURITY.md)
+[![Changelog](https://img.shields.io/badge/changelog-md-blue.svg)](./CHANGELOG.md)
+
+Public package containing shared Azure storage helpers for Plasius services.
+
+
+## Install
+
+```bash
+npm install @plasius/storage
+```
+
+## Usage
+
+```ts
+import { createShareClient } from "@plasius/storage";
+```
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## Governance
+
+- Security policy: [SECURITY.md](./SECURITY.md)
+- Code of conduct: [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)
+- ADRs: [docs/adrs](./docs/adrs)
+- Legal docs: [legal](./legal)
+
+## License
+
+MIT

package/SECURITY.md

@@ -0,0 +1,17 @@
+# Security Policy
+
+## Supported Versions
+
+We currently support the latest major version of this project. Older versions may not receive security updates.
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it privately by emailing us at [security@plasius.co.uk](mailto:security@plasius.co.uk). Please do not create a public issue for security-related matters.
+
+## Response Timeline
+
+We aim to acknowledge your report within 2 business days and to provide a more detailed response (including next steps and, if applicable, a timeline for a fix) within 7 business days.
+
+## Disclosure Policy
+
+We request that you give us the opportunity to address the vulnerability before publicly disclosing it. We will coordinate with you on public disclosure once a fix is available and deployed.

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+interface UploadOptions {
+    maxRetries?: number;
+    baseDelayMs?: number;
+}
+/**
+ * Uploads a user image to Azure File Share storage with retries and error handling.
+ * @param userId - The user's ID (used as directory name)
+ * @param version - The version number (used as file name)
+ * @param buffer - The file data as a Buffer
+ * @param contentType - The MIME type of the file
+ * @param options - Optional settings for retries and backoff
+ * @returns URL to the uploaded file
+ */
+export declare function uploadUserImageShare(userId: string, version: number, buffer: Buffer, contentType: string, options?: UploadOptions): Promise<string>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,UAAU,aAAa;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,MAAM,CAAC,CA6FjB"}

package/dist/index.js

@@ -0,0 +1,84 @@
+import { ShareServiceClient } from "@azure/storage-file-share";
+/**
+ * Uploads a user image to Azure File Share storage with retries and error handling.
+ * @param userId - The user's ID (used as directory name)
+ * @param version - The version number (used as file name)
+ * @param buffer - The file data as a Buffer
+ * @param contentType - The MIME type of the file
+ * @param options - Optional settings for retries and backoff
+ * @returns URL to the uploaded file
+ */
+export async function uploadUserImageShare(userId, version, buffer, contentType, options = {}) {
+    // Parameter validation
+    if (!process.env.AZURE_STORAGE_CONNECTION_STRING) {
+        throw new Error("AZURE_STORAGE_CONNECTION_STRING is not set in environment variables.");
+    }
+    if (!userId || typeof userId !== "string") {
+        throw new Error("userId is required and must be a string.");
+    }
+    if (typeof version !== "number" || isNaN(version)) {
+        throw new Error("version is required and must be a number.");
+    }
+    if (!buffer || !(buffer instanceof Buffer)) {
+        throw new Error("buffer is required and must be a Buffer.");
+    }
+    if (!contentType || typeof contentType !== "string") {
+        throw new Error("contentType is required and must be a string.");
+    }
+    const maxRetries = options.maxRetries ?? 3;
+    const baseDelayMs = options.baseDelayMs ?? 500;
+    const shareName = "avatars";
+    const directoryName = userId;
+    const fileName = `${version}.jpg`;
+    const serviceClient = ShareServiceClient.fromConnectionString(process.env.AZURE_STORAGE_CONNECTION_STRING);
+    const shareClient = serviceClient.getShareClient(shareName);
+    const directoryClient = shareClient.getDirectoryClient(directoryName);
+    const fileClient = directoryClient.getFileClient(fileName);
+    // Retry logic with exponential backoff
+    let attempt = 0;
+    let lastError = null;
+    while (attempt < maxRetries) {
+        try {
+            // Ensure share exists
+            await shareClient.createIfNotExists();
+            // Ensure directory exists
+            await directoryClient.createIfNotExists();
+            // Create file (set size)
+            await fileClient.create(buffer.length, {
+                fileHttpHeaders: { fileContentType: contentType },
+            });
+            // Upload content
+            await fileClient.uploadRange(buffer, 0, buffer.length);
+            // Return file URL
+            return fileClient.url;
+        }
+        catch (err) {
+            lastError = err;
+            if (err &&
+                typeof err === "object" &&
+                "message" in err &&
+                typeof err.message === "string") {
+                console.error(`Attempt ${attempt + 1} to upload user image failed: ${err.message}`);
+            }
+            else {
+                console.error(`Attempt ${attempt + 1} to upload user image failed:`, err);
+            }
+            // Exponential backoff with jitter
+            if (attempt < maxRetries - 1) {
+                const baseDelay = Math.pow(2, attempt) * baseDelayMs;
+                const jitter = Math.random() * baseDelay;
+                const delay = baseDelay / 2 + jitter; // Between 0.5x and 1.5x base delay
+                console.warn(`Backing off for ${Math.round(delay)} ms before retrying...`);
+                await new Promise((res) => setTimeout(res, delay));
+            }
+        }
+        attempt++;
+    }
+    const lastErrorMsg = lastError &&
+        typeof lastError === "object" &&
+        "message" in lastError &&
+        typeof lastError.message === "string"
+        ? lastError.message
+        : String(lastError ?? "");
+    throw new Error(`Failed to upload user image after ${maxRetries} attempts: ${lastErrorMsg}`);
+}

package/dist-cjs/index.d.ts

@@ -0,0 +1,16 @@
+interface UploadOptions {
+    maxRetries?: number;
+    baseDelayMs?: number;
+}
+/**
+ * Uploads a user image to Azure File Share storage with retries and error handling.
+ * @param userId - The user's ID (used as directory name)
+ * @param version - The version number (used as file name)
+ * @param buffer - The file data as a Buffer
+ * @param contentType - The MIME type of the file
+ * @param options - Optional settings for retries and backoff
+ * @returns URL to the uploaded file
+ */
+export declare function uploadUserImageShare(userId: string, version: number, buffer: Buffer, contentType: string, options?: UploadOptions): Promise<string>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist-cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,UAAU,aAAa;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,MAAM,CAAC,CA6FjB"}

package/dist-cjs/index.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadUserImageShare = uploadUserImageShare;
+const storage_file_share_1 = require("@azure/storage-file-share");
+/**
+ * Uploads a user image to Azure File Share storage with retries and error handling.
+ * @param userId - The user's ID (used as directory name)
+ * @param version - The version number (used as file name)
+ * @param buffer - The file data as a Buffer
+ * @param contentType - The MIME type of the file
+ * @param options - Optional settings for retries and backoff
+ * @returns URL to the uploaded file
+ */
+async function uploadUserImageShare(userId, version, buffer, contentType, options = {}) {
+    // Parameter validation
+    if (!process.env.AZURE_STORAGE_CONNECTION_STRING) {
+        throw new Error("AZURE_STORAGE_CONNECTION_STRING is not set in environment variables.");
+    }
+    if (!userId || typeof userId !== "string") {
+        throw new Error("userId is required and must be a string.");
+    }
+    if (typeof version !== "number" || isNaN(version)) {
+        throw new Error("version is required and must be a number.");
+    }
+    if (!buffer || !(buffer instanceof Buffer)) {
+        throw new Error("buffer is required and must be a Buffer.");
+    }
+    if (!contentType || typeof contentType !== "string") {
+        throw new Error("contentType is required and must be a string.");
+    }
+    const maxRetries = options.maxRetries ?? 3;
+    const baseDelayMs = options.baseDelayMs ?? 500;
+    const shareName = "avatars";
+    const directoryName = userId;
+    const fileName = `${version}.jpg`;
+    const serviceClient = storage_file_share_1.ShareServiceClient.fromConnectionString(process.env.AZURE_STORAGE_CONNECTION_STRING);
+    const shareClient = serviceClient.getShareClient(shareName);
+    const directoryClient = shareClient.getDirectoryClient(directoryName);
+    const fileClient = directoryClient.getFileClient(fileName);
+    // Retry logic with exponential backoff
+    let attempt = 0;
+    let lastError = null;
+    while (attempt < maxRetries) {
+        try {
+            // Ensure share exists
+            await shareClient.createIfNotExists();
+            // Ensure directory exists
+            await directoryClient.createIfNotExists();
+            // Create file (set size)
+            await fileClient.create(buffer.length, {
+                fileHttpHeaders: { fileContentType: contentType },
+            });
+            // Upload content
+            await fileClient.uploadRange(buffer, 0, buffer.length);
+            // Return file URL
+            return fileClient.url;
+        }
+        catch (err) {
+            lastError = err;
+            if (err &&
+                typeof err === "object" &&
+                "message" in err &&
+                typeof err.message === "string") {
+                console.error(`Attempt ${attempt + 1} to upload user image failed: ${err.message}`);
+            }
+            else {
+                console.error(`Attempt ${attempt + 1} to upload user image failed:`, err);
+            }
+            // Exponential backoff with jitter
+            if (attempt < maxRetries - 1) {
+                const baseDelay = Math.pow(2, attempt) * baseDelayMs;
+                const jitter = Math.random() * baseDelay;
+                const delay = baseDelay / 2 + jitter; // Between 0.5x and 1.5x base delay
+                console.warn(`Backing off for ${Math.round(delay)} ms before retrying...`);
+                await new Promise((res) => setTimeout(res, delay));
+            }
+        }
+        attempt++;
+    }
+    const lastErrorMsg = lastError &&
+        typeof lastError === "object" &&
+        "message" in lastError &&
+        typeof lastError.message === "string"
+        ? lastError.message
+        : String(lastError ?? "");
+    throw new Error(`Failed to upload user image after ${maxRetries} attempts: ${lastErrorMsg}`);
+}

package/docs/adrs/adr-0001-storage-package-scope.md

@@ -0,0 +1,21 @@
+# ADR-0001: Standalone @plasius/storage Package Scope
+
+- Date: 2026-02-11
+- Status: Accepted
+
+## Context
+
+This package was previously maintained as a workspace-only module inside
+`plasius-ltd-site`. External consumers and remote builds require it to be
+installable from npm without monorepo-local links.
+
+## Decision
+
+Move `@plasius/storage` to a standalone root package with independent build,
+test, governance, CI, and publish workflows.
+
+## Consequences
+
+- The package can be versioned and released independently.
+- `plasius-ltd-site` and other repositories can depend on npm-published versions.
+- Build and lint rules must no longer rely on monorepo-relative tsconfig paths.

package/docs/adrs/adr-0002-public-repo-governance.md

@@ -0,0 +1,24 @@
+# ADR-0002: Public Repository Governance Baseline
+
+- Date: 2026-02-11
+- Status: Accepted
+
+## Context
+
+Public npm distribution requires transparent contributor and security policy
+artifacts and consistent release automation.
+
+## Decision
+
+Include these baseline governance assets:
+
+- `CODE_OF_CONDUCT.md`
+- `CONTRIBUTORS.md`
+- `SECURITY.md`
+- `legal/` CLA documents
+- CI/CD GitHub Actions workflows
+
+## Consequences
+
+- Public contributors and consumers can follow a predictable governance process.
+- Release quality gates (build, test, coverage, publish) are standardized.

package/docs/adrs/adr-template.md

@@ -0,0 +1,35 @@
+# Architectural Decision Record (ADR)
+
+## Title
+
+> Concise, descriptive title of the decision.
+
+## Status
+
+- Proposed | Accepted | Rejected | Superseded | Deprecated
+- Date: YYYY-MM-DD
+- Version: 1.0
+
+## Context
+
+Describe the problem, constraints, and relevant background.
+
+## Decision
+
+Clear statement of the selected approach.
+
+## Alternatives Considered
+
+- Option A
+- Option B
+- Option C
+
+## Consequences
+
+- Positive outcomes
+- Negative outcomes / trade-offs
+- Follow-up work
+
+## References
+
+- https://adr.github.io/

package/legal/CLA-REGISTRY.csv

@@ -0,0 +1 @@
+type,github_handle,full_name,company,email,date,approver

package/legal/CLA.md

@@ -0,0 +1,22 @@
+# Contributor License Agreements (CLA)
+
+To protect the intellectual property of this project and ensure clarity of rights, all contributors must sign a Contributor License Agreement (CLA) before their first contribution.
+
+## Which CLA should I sign?
+
+- **Individual CLA**: If you are contributing personally and not on behalf of an employer, sign the [Individual CLA](INDIVIDUAL_CLA.md).
+- **Corporate CLA**: If you are contributing as part of your work for a company, the company should sign the [Corporate CLA](CORPORATE_CLA.md).
+
+## How to sign
+
+1. Download the appropriate CLA file (Individual or Corporate).
+2. Fill in the required details, sign, and date it.
+3. Email a PDF copy of the signed document to **[contributors@plasius.co.uk](mailto:contributors@plasius.co.uk)** with subject: `CLA – Individual` or `CLA – Corporate`.
+
+## Registry
+
+All signed CLAs are logged internally in the CLA registry (`CLA-REGISTRY.csv`).
+
+## Questions?
+
+If you have any questions about which CLA to sign or how the process works, please email **[contributors@plasius.co.uk](mailto:contributors@plasius.co.uk)**.

package/legal/CORPORATE_CLA.md

@@ -0,0 +1,57 @@
+# Corporate Contributor License Agreement (CLA)
+
+## Purpose
+
+This Corporate Contributor License Agreement ("Agreement") is intended to protect the intellectual property rights of the contributors and the project, ensure clear licensing terms for contributions, and maintain trust within the community. By signing this Agreement, the corporation agrees to the terms that facilitate the use, distribution, and modification of contributions under the project's licensing framework.
+
+## Agreement
+
+1. **Representation of Authority**  
+   The undersigned individual represents and warrants that they have the full legal authority to enter into this Agreement on behalf of the corporation named below ("Corporation") and to grant the rights contained herein.
+
+2. **Grant of Copyright License**  
+   The Corporation hereby grants to the project maintainers and users a perpetual, worldwide, non-exclusive, royalty-free, irrevocable copyright license to use, reproduce, prepare derivative works of, publicly display, publicly perform, sublicense, and distribute the contributions submitted to the project.
+
+3. **Grant of Patent License**  
+   The Corporation hereby grants to the project maintainers and users a perpetual, worldwide, non-exclusive, royalty-free, irrevocable license under any patent claims that are necessarily infringed by the contributions to make, use, sell, offer for sale, import, and otherwise dispose of the contributions or derivative works thereof.
+
+4. **Warranties and Representations**  
+   The Corporation represents and warrants that:
+
+- The contributions are the original work of the Corporation or that the Corporation has sufficient rights to grant the licenses herein.
+- The submission of the contributions does not violate any agreements or rights of third parties.
+
+5. **No Revocation**  
+   This license is granted on a perpetual basis and cannot be revoked, provided that the terms of this Agreement are met.
+
+6. **Governing Law**
+   This Agreement shall be governed by and construed in accordance with the laws of the United Kingdom, without regard to its conflict of laws principles.
+
+7. **Execution**
+
+This Agreement is effective upon signature by the authorized representative of the Corporation. Please sign and date this document, then email a scanned PDF copy to [contributors@plasius.co.uk](mailto:contributors@plasius.co.uk).
+
+---
+
+### **@plasius/api**
+
+**Corporation Legal Name:** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
+
+**Authorized Representative:** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
+
+**Title:** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
+
+**Email:** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
+
+**Date:** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
+
+**Signature:** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
+
+---
+
+## How to Sign
+
+- Download this file as a template.
+- Fill in the Corporation’s legal name, authorized representative, title, email, date, and provide a signature.
+- Sign and date the document.
+- Send a scanned copy of the signed Agreement to [contributors@plasius.co.uk](mailto:contributors@plasius.co.uk).

package/legal/INDIVIDUAL_CLA.md

@@ -0,0 +1,91 @@
+# Individual Contributor License Agreement (CLA)
+
+**Project:** @plasius/api (Plasius LTD)  
+**Version:** 1.0 — 2025‑09‑12  
+**Contact:** [contributors@plasius.co.uk](mailto:contributors@plasius.co.uk)
+
+---
+
+## 1. Definitions
+
+- **"You"** (or **"Contributor"**) means the individual signing this CLA and submitting Contributions to the Project.
+- **"Contribution"** means any original work of authorship, including code, documentation, data, designs, or feedback that You submit to the Project in any form (e.g., pull request, issue comment, email, file upload).
+- **"Project"** means the @plasius/api repositories and related materials owned or managed by **Plasius LTD**.
+
+## 2. Copyright License Grant
+
+You hereby grant to Plasius LTD a **perpetual, worldwide, non‑exclusive, transferable, sublicensable, royalty‑free, irrevocable** copyright license to:
+
+- use, reproduce, publicly display, publicly perform, modify, create derivative works of, and
+- distribute Contributions in source and object form,
+- and to **sublicense** these rights under any terms Plasius LTD chooses, including proprietary or open‑source licenses.
+
+## 3. Patent License Grant
+
+You hereby grant to Plasius LTD and its sublicensees a **perpetual, worldwide, non‑exclusive, transferable, royalty‑free, irrevocable** patent license to **make, have made, use, offer to sell, sell, import, and otherwise transfer** the Contribution and derivative works thereof, where such license applies only to patent claims that You **own or control** and that would be infringed by Your Contribution or its combination with the Project.
+
+## 4. Moral Rights & Attribution
+
+To the maximum extent permitted by applicable law, You **waive** and agree not to assert any moral rights (e.g., rights of attribution or integrity) in or to the Contribution against Plasius LTD. Plasius LTD may, but is not required to, credit You.
+
+## 5. Representations & Warranties
+
+You represent that:
+
+1. **Originality / Rights:** Each Contribution is Your original creation, or You have sufficient rights to submit it and grant the licenses above.
+2. **No Confidential Info:** Contributions **do not** include confidential information or trade secrets of any third party.
+3. **No Infringement:** To the best of Your knowledge, Contributions do not infringe any third‑party IP rights.
+4. **Employment / Contractor Status:** If Your employer or a third party might claim rights in Your Contribution, You have obtained **written permission** to make the Contribution and grant these licenses (attach or reference below), or Your Contribution is made **outside the scope** of your employment and without using your employer’s confidential information or resources.
+5. **Compliance:** You will follow the Project’s policies (e.g., Code of Conduct, Security Policy) and applicable laws.
+
+## 6. Third‑Party Code
+
+If Your Contribution includes code, data, or other material from a third party, You will **identify the material and its license** in the pull request or submission, and ensure it is **compatible** with the Project’s licensing model. You will not submit material subject to terms that require the Project to disclose proprietary source code (e.g., certain copyleft obligations) unless the Project has **pre‑approved** such inclusion in writing.
+
+## 7. Scope & Duration
+
+- This CLA covers **all past and future** Contributions You submit to the Project, unless and until You provide written notice to **revoke** it.
+- Revocation is **not retroactive**: rights granted for prior Contributions remain in effect.
+
+## 8. Disclaimer
+
+THE CONTRIBUTION IS PROVIDED “AS IS” WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON‑INFRINGEMENT.
+
+## 9. Governing Law & Jurisdiction
+
+This CLA is governed by the **laws of England and Wales**, and the courts of England and Wales shall have **exclusive jurisdiction** over any dispute arising out of or relating to it.
+
+## 10. Entire Agreement
+
+This CLA is the entire agreement between You and Plasius LTD regarding Contributions. It supersedes any prior discussions relating to Contributions. If any provision is held unenforceable, the remaining provisions remain in full force.
+
+---
+
+## 11. Contributor Information & Signature
+
+By signing below, You agree to the terms of this CLA for Your Contributions to the Project.
+
+**Full Name:** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
+
+**Email:** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
+
+**GitHub Handle:** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
+
+**Address (optional):** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
+
+**Employer (if applicable):** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
+
+**If employed:** ☐ I confirm Contributions are made outside the scope of employment **or** ☐ I have attached my employer’s written permission.
+
+**Signature:** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
+
+**Date (YYYY‑MM‑DD):** \_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_\_
+
+_Electronic signatures are accepted. You may type your name in the Signature field and email a PDF copy._
+
+**Submission:** Please email the signed CLA to **[contributors@plasius.co.uk](mailto:contributors@plasius.co.uk)** with subject line: `CLA – Individual – <GitHubHandle>`.
+
+**(Optional) Attachments / Notes:**
+
+- Employer permission letter (if required)
+- Third‑party license disclosures (if any)

package/package.json

@@ -0,0 +1,103 @@
+{
+  "name": "@plasius/storage",
+  "version": "1.0.0",
+  "main": "./dist-cjs/index.js",
+  "types": "./dist/index.d.ts",
+  "private": false,
+  "type": "module",
+  "description": "Azure storage for Plasius projects",
+  "scripts": {
+    "build": "tsc --build && npm run build:cjs",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:coverage:watch": "vitest --coverage",
+    "clean": "rimraf dist-cjs dist tsconfig.tsbuildinfo",
+    "reset:clean": "rm -rf node_modules package-lock.json && npm run clean",
+    "audit:ts": "tsc --noEmit --pretty",
+    "audit:eslint": "eslint \"{src,apps,packages}/**/*.{ts,tsx}\" --max-warnings=0 --ext .ts,.tsx",
+    "audit:deps": "depcheck --skip-missing=true",
+    "audit:npm": "npm audit --audit-level=moderate || true",
+    "audit:test": "vitest run --coverage",
+    "audit:all": "npm-run-all -l audit:ts audit:eslint audit:deps audit:npm audit:test",
+    "build:cjs": "tsc -p tsconfig.json --module commonjs --moduleResolution node --outDir dist-cjs --tsBuildInfoFile dist-cjs/tsconfig.tsbuildinfo",
+    "lint": "eslint .",
+    "prepare": "npm run build"
+  },
+  "author": "Plasius LTD <development@plasius.co.uk>",
+  "license": "MIT",
+  "peerDependencies": {
+    "@azure/cosmos": "^4.4.1",
+    "react": "^19.1.0"
+  },
+  "dependencies": {
+    "@azure/storage-file-share": "^12.27.0",
+    "@plasius/entity-manager": "^1.0.4",
+    "@plasius/schema": "^1.0.0"
+  },
+  "devDependencies": {
+    "@azure/cosmos": "^4.4.1",
+    "@types/node": "^24.3.1",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.1.8",
+    "@types/uuid": "^10.0.0",
+    "@typescript-eslint/eslint-plugin": "^8.38.0",
+    "@typescript-eslint/parser": "^8.38.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "ajv": "^6.12.6",
+    "depcheck": "^1.4.7",
+    "eslint": "^9.33.0",
+    "npm-run-all": "^4.1.5",
+    "react": "^19.1.0",
+    "tsx": "^4.20.3",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4",
+    "zod": "^4.0.17"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist-cjs/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "module": "./dist/index.js",
+  "files": [
+    "dist",
+    "dist-cjs",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CODE_OF_CONDUCT.md",
+    "CONTRIBUTORS.md",
+    "docs",
+    "legal"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Plasius-LTD/storage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Plasius-LTD/storage/issues"
+  },
+  "homepage": "https://github.com/Plasius-LTD/storage#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "funding": [
+    {
+      "type": "patreon",
+      "url": "https://www.patreon.com/c/plasiusltd/membership"
+    },
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/Plasius-LTD"
+    }
+  ],
+  "engines": {
+    "node": ">=22.12"
+  }
+}

package/src/index.ts

@@ -0,0 +1,116 @@
+import { ShareServiceClient } from "@azure/storage-file-share";
+
+interface UploadOptions {
+  maxRetries?: number;
+  baseDelayMs?: number;
+}
+
+/**
+ * Uploads a user image to Azure File Share storage with retries and error handling.
+ * @param userId - The user's ID (used as directory name)
+ * @param version - The version number (used as file name)
+ * @param buffer - The file data as a Buffer
+ * @param contentType - The MIME type of the file
+ * @param options - Optional settings for retries and backoff
+ * @returns URL to the uploaded file
+ */
+export async function uploadUserImageShare(
+  userId: string,
+  version: number,
+  buffer: Buffer,
+  contentType: string,
+  options: UploadOptions = {}
+): Promise<string> {
+  // Parameter validation
+  if (!process.env.AZURE_STORAGE_CONNECTION_STRING) {
+    throw new Error(
+      "AZURE_STORAGE_CONNECTION_STRING is not set in environment variables."
+    );
+  }
+  if (!userId || typeof userId !== "string") {
+    throw new Error("userId is required and must be a string.");
+  }
+  if (typeof version !== "number" || isNaN(version)) {
+    throw new Error("version is required and must be a number.");
+  }
+  if (!buffer || !(buffer instanceof Buffer)) {
+    throw new Error("buffer is required and must be a Buffer.");
+  }
+  if (!contentType || typeof contentType !== "string") {
+    throw new Error("contentType is required and must be a string.");
+  }
+
+  const maxRetries = options.maxRetries ?? 3;
+  const baseDelayMs = options.baseDelayMs ?? 500;
+
+  const shareName = "avatars";
+  const directoryName = userId;
+  const fileName = `${version}.jpg`;
+
+  const serviceClient = ShareServiceClient.fromConnectionString(
+    process.env.AZURE_STORAGE_CONNECTION_STRING
+  );
+  const shareClient = serviceClient.getShareClient(shareName);
+  const directoryClient = shareClient.getDirectoryClient(directoryName);
+  const fileClient = directoryClient.getFileClient(fileName);
+
+  // Retry logic with exponential backoff
+  let attempt = 0;
+  let lastError: unknown = null;
+  while (attempt < maxRetries) {
+    try {
+      // Ensure share exists
+      await shareClient.createIfNotExists();
+      // Ensure directory exists
+      await directoryClient.createIfNotExists();
+      // Create file (set size)
+      await fileClient.create(buffer.length, {
+        fileHttpHeaders: { fileContentType: contentType },
+      });
+      // Upload content
+      await fileClient.uploadRange(buffer, 0, buffer.length);
+      // Return file URL
+      return fileClient.url;
+    } catch (err: unknown) {
+      lastError = err;
+      if (
+        err &&
+        typeof err === "object" &&
+        "message" in err &&
+        typeof (err as { message: unknown }).message === "string"
+      ) {
+        console.error(
+          `Attempt ${attempt + 1} to upload user image failed: ${
+            (err as { message: string }).message
+          }`
+        );
+      } else {
+        console.error(
+          `Attempt ${attempt + 1} to upload user image failed:`,
+          err
+        );
+      }
+      // Exponential backoff with jitter
+      if (attempt < maxRetries - 1) {
+        const baseDelay = Math.pow(2, attempt) * baseDelayMs;
+        const jitter = Math.random() * baseDelay;
+        const delay = baseDelay / 2 + jitter; // Between 0.5x and 1.5x base delay
+        console.warn(
+          `Backing off for ${Math.round(delay)} ms before retrying...`
+        );
+        await new Promise((res) => setTimeout(res, delay));
+      }
+    }
+    attempt++;
+  }
+  const lastErrorMsg =
+    lastError &&
+    typeof lastError === "object" &&
+    "message" in lastError &&
+    typeof (lastError as { message: unknown }).message === "string"
+      ? (lastError as { message: string }).message
+      : String((lastError as Error) ?? "");
+  throw new Error(
+    `Failed to upload user image after ${maxRetries} attempts: ${lastErrorMsg}`
+  );
+}