@docbox-nz/hapi-gateway 0.1.0

package/.eslintignore

@@ -0,0 +1,6 @@
+// .eslintignore
+build/*
+dist/*
+public/*
+**/out/*
+**/node_modules/*

package/.eslintrc

@@ -0,0 +1,131 @@
+{
+  "root": true,
+  "env": {
+    "browser": true,
+    "es2021": true,
+  },
+  "plugins": [
+    "perfectionist",
+    "unused-imports",
+    "@typescript-eslint",
+    "prettier"
+  ],
+  "extends": [
+    "airbnb",
+    "airbnb-typescript",
+    "airbnb/hooks",
+    "prettier"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module",
+    "project": "./tsconfig.json",
+  },
+  "settings": {
+    "import/resolver": {
+      "typescript": {
+        "alwaysTryTypes": true,
+      },
+    },
+  },
+  "rules": {
+    "max-classes-per-file": 10,
+    "no-return-await": 0,
+    "@typescript-eslint/return-await": 0,
+    "no-await-in-loop": 0,
+    "no-restricted-syntax": [
+      "error",
+      "ForInStatement",
+      "LabeledStatement",
+      "WithStatement"
+    ],
+    "no-alert": 0,
+    "camelcase": 0,
+    "no-console": 0,
+    "no-continue": 0,
+    "no-unused-vars": 0,
+    "no-param-reassign": 0,
+    "no-underscore-dangle": 0,
+    "no-restricted-exports": 0,
+    "no-promise-executor-return": 0,
+    "import/prefer-default-export": 0,
+    "@typescript-eslint/naming-convention": 0,
+    "jsx-a11y/control-has-associated-label": 0,
+    "@typescript-eslint/no-use-before-define": 0,
+    "@typescript-eslint/no-shadow": 0,
+    "prefer-destructuring": [
+      1,
+      {
+        "object": true,
+        "array": false,
+      },
+    ],
+    "@typescript-eslint/no-unused-vars": [
+      1,
+      {
+        "args": "none",
+        "argsIgnorePattern": "^_",
+        "varsIgnorePattern": "^_",
+        "caughtErrorsIgnorePattern": "^_",
+      },
+    ],
+    // unused-imports
+    // https://www.npmjs.com/package/eslint-plugin-unused-imports
+    "unused-imports/no-unused-imports": 1,
+    "unused-imports/no-unused-vars": [
+      0,
+      {
+        "vars": "all",
+        "varsIgnorePattern": "^_",
+        "args": "after-used",
+        "argsIgnorePattern": "^_",
+      },
+    ],
+    // perfectionist
+    // https://eslint-plugin-perfectionist.azat.io/
+    "perfectionist/sort-named-imports": [
+      1,
+      {
+        "order": "asc",
+        "type": "line-length",
+      },
+    ],
+    "perfectionist/sort-named-exports": [
+      1,
+      {
+        "order": "asc",
+        "type": "line-length",
+      },
+    ],
+    "perfectionist/sort-exports": [
+      1,
+      {
+        "order": "asc",
+        "type": "line-length",
+      },
+    ],
+    "perfectionist/sort-imports": [
+      1,
+      {
+        "order": "asc",
+        "type": "line-length",
+        "newlines-between": "always",
+        "groups": [
+          [
+            "builtin",
+            "external"
+          ],
+          [
+            "parent",
+            "sibling",
+            "index"
+          ],
+        ],
+        "internal-pattern": [
+          "src/**"
+        ],
+      },
+    ],
+  },
+}

package/.prettierignore

@@ -0,0 +1,11 @@
+build/*
+dist/*
+public/*
+**/out/*
+**/.next/*
+**/node_modules/*
+
+package-lock.json
+yarn.lock
+
+.eslintrc

package/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "printWidth": 100,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "tabWidth": 2
+}

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Provida 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,152 @@
+# 📦 @docbox-nz/hapi-gateway
+
+Docbox Gateway implementation for hapi 
+
+Provides routes for forwarding requests to docbox and methods for enforcing access control over said routes
+
+## Requirements
+- Hapi.js v20.1.0 or newer
+- Node.js 20+
+
+## Installation
+
+To install the gateway use the following command (adjusted for your desired package manager):
+
+```sh
+npm i @docbox-nz/hapi-gateway
+```
+
+You will also need to ensure that you have `@hapi/hapi` installed this plugin supports versions `^20.1.0 || ^21.0.0`
+
+
+## Plugin setup
+
+For a simple installation where not much additional logic is required, you can add the following to your server setup
+
+```js
+import { DocboxGateway } from "@docbox-nz/hapi-gateway";
+
+server.register({
+  plugin: DocboxGateway,
+  options: {
+    // Prefix all routes with /data
+    basePath: '/data',
+    // Base request options for docbox routes
+    baseRouteOptions: { },
+    // URL for the docbox API
+    docboxBaseURL: "http://docbox-server",
+
+    // Get the tenant for a request
+    getRequestTenant(request) {
+      // ..derive your target tenant
+      // this can be hard-coded for single tenant setups
+      return { id: '81284060-9542-4d66-9731-49ca3eb93bf9', env: "Development"}
+    },
+
+    // Get the user for a request
+    getRequestUser(request) {
+      // ..derive your request user
+      return {
+        id: "dd5ba8b5-7da2-4e8b-b255-9641faece80e",
+        name: "Example User",
+        imageId: "https://example.com/example.png"
+      }
+    },
+
+    // Check request read access
+    async isAllowedRead(request, scope, path) {
+      // ..assert request is allowed to access scope
+      return true;
+    },
+
+    // Check request write access
+    async isAllowedWrite(request, scope, path) {
+      // ..assert request is allowed to access scope
+      return true;
+    },
+  }
+});
+```
+
+## Complex Routing Setup
+
+If you have a more complex routing setup for your hapi app, you can use the `createDocboxRoutes` function to create a docbox setup and obtain a list of routes that you can manually add using `server.route`
+
+```js
+import { createDocboxRoutes } from "@docbox-nz/hapi-gateway";
+
+const routes = createDocboxRoutes({
+  // Prefix all routes with /data
+  basePath: '/data',
+  // Base request options for docbox routes
+  baseRouteOptions: { },
+  // URL for the docbox API
+  docboxBaseURL: "http://docbox-server",
+
+  // Get the tenant for a request
+  getRequestTenant(request) {
+    // ..derive your target tenant
+    // this can be hard-coded for single tenant setups
+    return { id: '81284060-9542-4d66-9731-49ca3eb93bf9', env: "Development"}
+  },
+
+  // Get the user for a request
+  getRequestUser(request) {
+    // ..derive your request user
+    return {
+      id: "dd5ba8b5-7da2-4e8b-b255-9641faece80e",
+      name: "Example User",
+      imageId: "https://example.com/example.png"
+    }
+  },
+
+  // Check request read access
+  async isAllowedRead(request, scope, path) {
+    // ..assert request is allowed to access scope
+    return true;
+  },
+
+  // Check request write access
+  async isAllowedWrite(request, scope, path) {
+    // ..assert request is allowed to access scope
+    return true;
+  },
+});
+
+module.exports = routes;
+```
+
+
+## Example access control 
+
+Access control is enforced on a scope level, you should check the `scope` (Document box scope) and decide whether the request should be allowed based 
+on some information extracted from the request (or some other available context)
+
+> [!NOTE]
+>
+> The `isAllowedRead` and `isAllowedWrite` functions can be sync or async, this allows you to perform additional logic such as checking your database for permission requirements
+>
+> `isAllowedWrite` also enforces the access control for creating new document boxes. Requests to `POST /box` are document box creation requests.
+
+```js
+
+function isAllowedWrite(request, scope, path) {
+
+    // Get authenticated user scopes
+    const userScopes = request.auth.credentials.scope
+
+    // User is trying to access the "admin-area" scope
+    if (scope === "admin-area") {
+
+        // Ensure the user has the required admin scope
+        if (userScopes.includes('admin')) {
+            return true;
+        }
+
+    }
+
+    // Deny by default
+    return false;
+} 
+
+```

package/cspell.json

@@ -0,0 +1,6 @@
+{
+    "words": [
+        "Docbox",
+        "Jacobtread"
+    ]
+}

package/dist/api/adminService.d.ts

@@ -0,0 +1,16 @@
+import { DocboxAdminSearchRequest, DocboxSearchResponseAdmin } from '../types';
+import { DocboxClient } from './client';
+export declare class AdminService {
+    private client;
+    constructor(client: DocboxClient);
+    /**
+     * Perform an admin search across multiple document boxes.
+     *
+     * This function will only work on your server handling authentication
+     * you should not allow the frontend to access these endpoints
+     *
+     * @param data Search request data
+     * @returns The search results
+     */
+    search(data: DocboxAdminSearchRequest): Promise<DocboxSearchResponseAdmin>;
+}

package/dist/api/boxService.d.ts

@@ -0,0 +1,43 @@
+import { DocboxSearchRequest, DocboxSearchResponse, DocumentBoxResponse, DocumentBoxScope, DocumentBoxStats } from '../types';
+import { DocboxClient } from './client';
+export declare class BoxService {
+    private client;
+    constructor(client: DocboxClient);
+    /**
+     * Get a document box for a scope
+     *
+     * @param scope Scope of the document box to get
+     * @param createIfMissing Whether to create the document box if it doesn't exist
+     */
+    get(scope: DocumentBoxScope, createIfMissing?: boolean): Promise<DocumentBoxResponse>;
+    /**
+     * Creates a new document box optional returning an existing one if there is one available
+     *
+     * @param scope Scope for the document box to create
+     * @param allowExisting Whether to allow returning an existing document box (If one is present)
+     * @returns The created document box
+     */
+    create(scope: DocumentBoxScope, allowExisting?: boolean): Promise<DocumentBoxResponse>;
+    /**
+     * Delete a specific document vox
+     *
+     * @param scope Scope of the document box to delete
+     * @returns
+     */
+    delete(scope: DocumentBoxScope): Promise<any>;
+    /**
+     * Search within the provided document box
+     *
+     * @param scope The scope of the document box to search
+     * @param data Search request data
+     * @returns The search results
+     */
+    search(scope: DocumentBoxScope, data: DocboxSearchRequest): Promise<DocboxSearchResponse>;
+    /**
+     * Get statistics for the provided document box
+     *
+     * @param scope The scope of the document box
+     * @returns The box stats
+     */
+    stats(scope: DocumentBoxScope): Promise<DocumentBoxStats>;
+}

package/dist/api/client.d.ts

@@ -0,0 +1,45 @@
+import type { AxiosRequestConfig, AxiosInstance } from 'axios';
+import { FileService } from './fileService';
+import { BoxService as DocumentBoxService } from './boxService';
+import { LinkService } from './linkService';
+import { FolderService } from './folderService';
+import { TaskService } from './taskService';
+import { AdminService } from './adminService';
+export declare class DocboxClient {
+    client: AxiosInstance;
+    /**
+     * Document box related operations
+     */
+    documentBox: DocumentBoxService;
+    /**
+     * Task related operations
+     */
+    task: TaskService;
+    /**
+     * File related operations
+     */
+    file: FileService;
+    /**
+     * Link related operations
+     */
+    link: LinkService;
+    /**
+     * Folder related operations
+     */
+    folder: FolderService;
+    /**
+     * Admin related operations
+     */
+    admin: AdminService;
+    /**
+     * Creates a new docbox
+     *
+     * @param client
+     */
+    constructor(client: AxiosInstance);
+    httpGet<T = any, D = any>(url: string, config?: AxiosRequestConfig<D>): Promise<T>;
+    httpPost<T = any, D = any>(url: string, data?: D, config?: AxiosRequestConfig<D>): Promise<T>;
+    httpPut<T = any, D = any>(url: string, data?: D, config?: AxiosRequestConfig<D>): Promise<T>;
+    httpPatch<T = any, D = any>(url: string, data?: D, config?: AxiosRequestConfig<D>): Promise<T>;
+    httpDelete<T = any, D = any>(url: string, config?: AxiosRequestConfig<D>): Promise<T>;
+}

package/dist/api/docboxFile.d.ts

@@ -0,0 +1,15 @@
+import { DocFile } from '../types/file';
+declare let FileGlobal: {
+    new (fileBits: BlobPart[], fileName: string, options?: FilePropertyBag): File;
+    prototype: File;
+};
+/**
+ * Wrapper around the browser File type to allow using a docbox file
+ * in place when handling already uploaded files in a form
+ */
+export declare class DocboxFile extends FileGlobal {
+    file: DocFile;
+    get size(): number;
+    constructor(file: DocFile);
+}
+export {};