@_linked/server 1.0.8

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/server" }
+  ],
+  "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/server
+
+## 1.0.8
+
+### Patch Changes
+
+- [`bb74f32`](https://github.com/linked-cm/server/commit/bb74f320c407db168300c78c8aea005f2dff3d0e) - Initial release under the new publishing setup.

package/package.json

@@ -0,0 +1,106 @@
+{
+  "name": "@_linked/server",
+  "description": "HTTP server & utilities for LINCD applications, running on node.js.",
+  "author": {
+    "name": "René Verheij",
+    "url": "https://github.com/flyon",
+    "email": "rpwverheij@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": ""
+  },
+  "version": "1.0.8",
+  "linkedPackage": true,
+  "main": "lib/cjs/index.js",
+  "types": "dist/lincd-server.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",
+    "server",
+    "nodejs",
+    "express",
+    "linked data",
+    "interoperable",
+    "semantic web",
+    "web3"
+  ],
+  "dependencies": {
+    "@_linked/cli": "^1.2",
+    "@_linked/core": "^2.2.1",
+    "@_linked/server-utils": "~1.0",
+    "adm-zip": "^0.5.16",
+    "archiver": "^7.0.1",
+    "autoprefixer": "^10.4.18",
+    "body-parser": "^1.20.2",
+    "chalk": "4.1.2",
+    "compression": "^1.7.4",
+    "cors": "^2.8.5",
+    "cron": "^4.3.4",
+    "express": "^4.18.3",
+    "fetch-cookie": "^3.1.0",
+    "is-object": "^1.0.2",
+    "lincd-sioc": "~1.0",
+    "n3": "^1.17.2",
+    "node-addon-api": "^8.2.2",
+    "node-hook": "^1.0.0",
+    "open": "^8.4.0",
+    "proper-lockfile": "^4.1.2",
+    "react": "^18.2",
+    "react-dom": "^18.2",
+    "react-error-boundary": "^4.0.13",
+    "react-router-dom": "^6.22.3",
+    "rimraf": "^5.0.5",
+    "sharp": "^0.34.4",
+    "tough-cookie": "^6.0.0",
+    "tsconfig-to-dual-package": "^1.2.0",
+    "typescript": "^5.7.3",
+    "webpack": "^5.90.3",
+    "webpack-dev-middleware": "^7.0.0",
+    "webpack-hot-middleware": "^2.26.1",
+    "zip-a-folder": "^3.1.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.7",
+    "@types/react-dom": "^18.0.6",
+    "cross-env": "^7.0.3",
+    "prettier": "3.2.5",
+    "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/readme.md

@@ -0,0 +1,205 @@
+# LINCD Server
+
+This package provides a `LincdServer` which can be used to instantiate a LINCD backend environment on node.js.
+
+If you use `npx lincd-cli create-app [name]` it will already set everything up for you to use `LincdServer`.
+To see how it's used, open `your-site/backend/server.js`.
+
+If you require any additional features, feel free to make a request at the LINCD Discord server.
+If you want to further adjust the functionality of LincdServer yourself, either extend it or clone this repo locally.
+
+---
+
+## Table of contents
+
+- [Environment Variables](#environment-variables)
+- [Calling methods on the backend](#calling-methods-on-the-backend)
+  - [Shape providers](#shape-providers)
+  - [Generic backend providers](#generic-backend-providers)
+  - [Gotchas](#gotchas)
+- [Shapes](#shapes)
+  - [LocalFileStore](#localfilestore)
+- [TODO](#todo)
+
+---
+
+## Environment Variables
+
+```properties
+# The port on which the server will listen
+PORT=3000
+
+# A descriptive URI for where the app's data can live
+DATA_ROOT=https://app.my-site.com/data
+
+# The site's URL - will also be used for LocalFileStore
+SITE_ROOT=http://localhost:3000  # or https://app.my-site.com
+
+# "development" or "production"
+NODE_ENV=development
+```
+
+## Calling methods on the backend
+
+When you use LincdServer, you can also implement backend methods that you can access from the frontend.
+
+There is two ways to do this:
+
+### Shape providers
+
+With Shape providers you can connect shapes to a backend method.
+
+Let's say for example you want to send an email to a specific person from the server.
+You could do that from a Person shape like so:
+
+```typescript
+import { linkedShape } from '../package';
+import { Shape } from '@_linked/core/lib/shapes/Shape';
+import { Server } from 'lincd-server/lib/utils/Server';
+
+@linkedShape
+export class Person extends Shape {
+  sendEmail(subject: string, message: string): Promise<boolean> {
+    return Server.call(this, 'sendEmail', subject, message);
+  }
+}
+```
+
+Note that `Server.call()` first takes the instance of the shape, then the method name and than any number of arguments
+to be passed on.
+
+To implement the backend, create `src/shapes/PersonProvider.ts`:
+
+```typescript
+import Person from './Person';
+import { ShapeProvider } from 'lincd-server-utils/lib/utils/ShapeProvider';
+
+export class PersonProvider extends ShapeProvider {
+  static shape = Person;
+
+  static sendEmail(person: Person, subject: string, message: string): boolean {
+    //send email to person
+    //mail(person.mailbox,subject,message);
+  }
+}
+```
+
+Here, PersonProvider first of all registers itself as a provider of the `Person` shape with `static shape = Person`.
+
+Then it implements the method (sendEmail()) as a a _static_ method, which receives an instance of the shape it is
+connected to as its first argument.
+
+To make sure the provider is _compiled_ but _not bundled_ you need to add it to `tsconfig`.
+
+The recommended way to do that is with a providers index file `src/providers.ts`.
+This file will re-export all providers of your package:
+
+```typescript
+//src/providers.ts
+export * from './shapes/PersonProvider';
+```
+
+Finally, add `providers.ts` to your `src/tsconfig.json`:
+
+```json5
+//tsconfig.json
+{
+  //...
+  files: ['./src/index.ts', './src/providers.ts'],
+}
+```
+
+That's all that's required to connect your frontend shapes to backend code.
+
+### Generic backend providers
+
+Sometimes you want to exchange data with the backend without any specific shape being involved.
+
+For such generic backend methods, you can use generic backend providers:
+
+Add a src/backend.ts file and include it in tsconfig.json:
+
+```json5
+//tsconfig.json
+{
+  //...
+  files: ['./src/index.ts', './src/backend.ts'],
+}
+```
+
+In `backend.ts`, export a default class that implements `IBackendProvider`.
+In this class you can implement methods, which you can then call from the frontend.
+
+For example:
+
+```typescript
+//src/backend.ts
+import { IBackendProvider } from 'lincd-server/lib/interfaces/IBackendProvider';
+
+export default class MyPackageBackendProvider implements IBackendProvider {
+  login(email: string, password: string) {
+    //do login
+    return Promise.resolve(user);
+  }
+}
+```
+
+With this example you could call the login method from the frontend like so:
+
+```typescript
+import { packageName } from '../package';
+import { Server } from 'lincd-server/lib/utils/Server';
+
+Server.call(packageName, 'login', email, password).then((user) => {
+  //...
+});
+```
+
+Note that you can have **only one** generic backend provider per package.
+
+### Gotchas
+
+**The packageName you pass to Server.call() must match with the package that contains the provider.**
+
+If you get a warning on the backend saying
+
+```
+Generic provider [providerName] of [packageName] does not have a method called [methodName]
+```
+
+then make sure that the `packageName` you pass to `Server.call(packageName)` is imported from _the same package_ as
+where the provider lives. Generally, this means you call `Server.call` from a component in the same package as the
+Provider (and import packageName from `src/package.ts`). If you want to call a method from another package, then import
+packageName from that package, or manually type it.
+
+## Shapes
+
+This section will be a brief overview of the shapes that are included in this package, along with example usage of each
+shape.
+
+### LocalFileStore
+
+This is the default file store for LINCD. It is a simple file store that stores files in a local directory. Its usage
+follows the general pattern of other file stores in LINCD:
+
+- Define all storage locations when the server or application starts up
+- Access methods of the file store through the `LinkedFileStorage` class
+  - e.g. `LinkedFileStorage.saveFile("path/to/save-file.as", fileBuffer)`
+
+It's important to note that this file store is not suitable for frontend usage - it's intended to be used in an
+environment that has access to the [`fs` module](https://nodejs.org/api/fs.html).
+
+```ts
+import { LinkedFileStorage } from '@_linked/core/lib/utils/LinkedFileStorage';
+import { LocalFileStore } from 'lincd-server/lib/shapes/LocalFileStore';
+import path from 'path';
+
+const pathToStore = path.join(process.cwd(), 'my-file-store');
+const store = new LocalFileStore('my-file-store', pathToStore);
+LinkedFileStorage.setDefaultStore(store);
+```
+
+## TODO
+
+- [ ] Add tests
+- [ ] Refactor `NodeFileStore` to `LocalQuadStore` as to not confuse FileStores with QuadStores

package/styles/apply-css-variables.css

@@ -0,0 +1,10 @@
+@use 'sass:meta';
+
+/*css variable*/
+:root {
+  --font-color: #{meta.inspect($fontColor)};
+  --primary-color: #{meta.inspect($primaryColor)};
+}
+
+/*we COULD overwrite the variables after setting them, if we wanted to avoid people from using the SCSS variables instead of the CSS variables*/
+/*$fontColor: null;*/

package/styles/css-variables.css

@@ -0,0 +1,56 @@
+/*initiate sass variables (they will later be converted to CSS variables in apply-css-variables.scss)*/
+:root {
+  --fontColor: #333333;
+  --primaryColor: #00bfff;
+  --onPrimaryColor: #ffffff;
+  --primaryContainer: lighten($primaryColor, 40%);
+  --onPrimaryContainer: #333333;
+  --secondaryColor: #67fcd4;
+  --onSecondaryColor: #ffffff;
+  --errorColor: #ff0000;
+  --warningColor: #ffa500;
+  --infoColor: #0000ff;
+  --successColor: #008000;
+  --backgroundColor: #ffffff;
+  --grayColor: #cccccc;
+  --fontFamily: 'Roboto', sans-serif;
+  --fontSize: 1rem;
+  --lineHeight: 1.5;
+  --borderRadius: 0.25rem;
+  --borderWidth: 1px;
+  --borderColor: #cccccc;
+  --borderStyle: solid;
+  --boxShadow: 0 0 0 1px rgba(0, 0, 0, 0.05), 0 1px 2px 0 rgba(0, 0, 0, 0.1);
+  --boxShadowHover: 0 0 0 1px rgba(0, 0, 0, 0.1), 0 2px 4px 0 rgba(0, 0, 0, 0.2);
+  --boxShadowActive: 0 0 0 1px rgba(0, 0, 0, 0.1),
+    0 1px 2px 0 rgba(0, 0, 0, 0.1);
+  --boxShadowFocus: 0 0 0 1px rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.1);
+  --boxShadowError: 0 0 0 1px rgba(255, 0, 0, 0.1),
+    0 1px 2px 0 rgba(255, 0, 0, 0.1);
+  --boxShadowWarning: 0 0 0 1px rgba(255, 165, 0, 0.1),
+    0 1px 2px 0 rgba(255, 165, 0, 0.1);
+  --boxShadowInfo: 0 0 0 1px rgba(0, 0, 255, 0.1),
+    0 1px 2px 0 rgba(0, 0, 255, 0.1);
+  --boxShadowSuccess: 0 0 0 1px rgba(0, 128, 0, 0.1),
+    0 1px 2px 0 rgba(0, 128, 0, 0.1);
+  --boxShadowGray: 0 0 0 1px rgba(204, 204, 204, 0.1),
+    0 1px 2px 0 rgba(204, 204, 204, 0.1);
+  --boxShadowBackground: 0 0 0 1px rgba(255, 255, 255, 0.1),
+    0 1px 2px 0 rgba(255, 255, 255, 0.1);
+  --boxShadowText: 0 0 0 1px rgba(51, 51, 51, 0.1),
+    0 1px 2px 0 rgba(51, 51, 51, 0.1);
+  --boxShadowPrimary: 0 0 0 1px rgba(0, 191, 255, 0.1),
+    0 1px 2px 0 rgba(0, 191, 255, 0.1);
+  --boxShadowSecondary: 0 0 0 1px rgba(103, 252, 212, 0.1),
+    0 1px 2px 0 rgba(103, 252, 212, 0.1);
+
+  /*error*/
+  /*warning*/
+  /*info*/
+  /*success*/
+  //
+  /*text*/
+  /*background*/
+  /*gray*/
+  //
+}

package/styles/variables.css

@@ -0,0 +1,54 @@
+/*initiate sass variables (they will later be converted to CSS variables in apply-css-variables.scss)*/
+$fontColor: #333333;
+$primaryColor: #00bfff;
+$onPrimaryColor: #ffffff;
+$primaryContainer: lighten($primaryColor, 40%);
+$onPrimaryContainer: #333333;
+
+$secondaryColor: #67fcd4;
+$onSecondaryColor: #ffffff;
+
+$errorColor: #ff0000;
+$warningColor: #ffa500;
+$infoColor: #0000ff;
+$successColor: #008000;
+$backgroundColor: #ffffff;
+$grayColor: #cccccc;
+$fontFamily: 'Roboto', sans-serif;
+$fontSize: 1rem;
+$lineHeight: 1.5;
+$borderRadius: 0.25rem;
+$borderWidth: 1px;
+$borderColor: #cccccc;
+$borderStyle: solid;
+$boxShadow: 0 0 0 1px rgba(0, 0, 0, 0.05), 0 1px 2px 0 rgba(0, 0, 0, 0.1);
+$boxShadowHover: 0 0 0 1px rgba(0, 0, 0, 0.1), 0 2px 4px 0 rgba(0, 0, 0, 0.2);
+$boxShadowActive: 0 0 0 1px rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.1);
+$boxShadowFocus: 0 0 0 1px rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.1);
+$boxShadowError: 0 0 0 1px rgba(255, 0, 0, 0.1),
+  0 1px 2px 0 rgba(255, 0, 0, 0.1);
+$boxShadowWarning: 0 0 0 1px rgba(255, 165, 0, 0.1),
+  0 1px 2px 0 rgba(255, 165, 0, 0.1);
+$boxShadowInfo: 0 0 0 1px rgba(0, 0, 255, 0.1), 0 1px 2px 0 rgba(0, 0, 255, 0.1);
+$boxShadowSuccess: 0 0 0 1px rgba(0, 128, 0, 0.1),
+  0 1px 2px 0 rgba(0, 128, 0, 0.1);
+$boxShadowGray: 0 0 0 1px rgba(204, 204, 204, 0.1),
+  0 1px 2px 0 rgba(204, 204, 204, 0.1);
+$boxShadowBackground: 0 0 0 1px rgba(255, 255, 255, 0.1),
+  0 1px 2px 0 rgba(255, 255, 255, 0.1);
+$boxShadowText: 0 0 0 1px rgba(51, 51, 51, 0.1),
+  0 1px 2px 0 rgba(51, 51, 51, 0.1);
+$boxShadowPrimary: 0 0 0 1px rgba(0, 191, 255, 0.1),
+  0 1px 2px 0 rgba(0, 191, 255, 0.1);
+$boxShadowSecondary: 0 0 0 1px rgba(103, 252, 212, 0.1),
+  0 1px 2px 0 rgba(103, 252, 212, 0.1);
+
+/*error*/
+/*warning*/
+/*info*/
+/*success*/
+//
+/*text*/
+/*background*/
+/*gray*/
+//

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"
+  }
+}