@evenicanpm/portal-dms-adapaters 1.4.0

package/package.json

@@ -0,0 +1,26 @@
+{
+	"name": "@evenicanpm/portal-dms-adapaters",
+	"version": "1.4.0",
+	"description": "",
+	"license": "ISC",
+	"author": "",
+	"type": "module",
+	"scripts": {
+		"test": "echo \"Error: no test specified\" && exit 1",
+		"format": "npx @biomejs/biome format --write ./src",
+		"build": "npx tsc"
+	},
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"types": "./dist/index.d.ts",
+	"devDependencies": {
+		"@types/node": "^25.3.0",
+		"typescript": "^5.6.3"
+	},
+	"dependencies": {
+		"@evenicanpm/storefront-portal-types-schemas": "*",
+		"zod": "^3.0.0"
+	},
+	"gitHead": "0614726ec6b7ce9564706514a6b756b390a13e96"
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./paperless/client";
+export * from "./paperless/config";

package/src/paperless/client.ts

@@ -0,0 +1,260 @@
+/**
+ *
+ * @module PaperlessProvider
+ * @category dms-provider
+ * Pure functions for extracting data from paperless-ngx
+ */
+import type { TableViewParams } from "@evenicanpm/storefront-portal-types-schemas";
+
+/**
+ * Paperless-Specific document config parameters.
+ */
+export interface PaperlessDocConfig {
+	/** Paperless uses type for broad category of document */
+	type: string;
+	/** Paperless tags */
+	tags: string[];
+	/** Property names to map back from papaless to the UI */
+	paperlessToPortalMap: Record<string, string>;
+}
+
+/**
+ * Configuration for Paperless Client
+ */
+export interface PaperlessClientConfig {
+	/** Credentials username */
+	username: string;
+	/** Credentials password */
+	password: string;
+	/** Base of paperless web-server */
+	baseUrl: string;
+	/** The endpoint prefix to fetch docs from paperless */
+	documentEndpoint: string;
+	tenantField: string;
+	customFieldsEndpoint: string;
+}
+
+/**
+ * Input for building a REST URL to fetch documents from Paperless
+ */
+interface PaperlessUrlInput {
+	config: PaperlessClientConfig;
+	params: TableViewParams;
+	paperlessParams: PaperlessDocConfig;
+	/** Property name to filter by for multi-tenancy so customer only sees their own docs */
+	customerId: string;
+	canViewAll: boolean;
+	docId?: string;
+}
+
+/**
+ *
+ * Builds URL for fetching documents from Paperless.
+ * Takes credentials, parameters and document settings and Builds
+ * a fetch-ready URL.
+ *
+ * @param PaperlessAuth Credentials for paperless basic auth.
+ *
+ */
+export const buildPaperlessRESTUrl = ({
+	config,
+	params,
+	paperlessParams,
+	customerId,
+	canViewAll,
+}: PaperlessUrlInput): Request => {
+	const { username, password, tenantField } = config;
+
+	// Prepare data for request
+	const encodedCredentials = Buffer.from(`${username}:${password}`).toString(
+		"base64",
+	);
+
+	const queryParams = mapParamsToQueryString({
+		params,
+		paperlessParams,
+		tenantField,
+		customerId,
+		canViewAll,
+	});
+
+	const url = queryParams
+		? `${config.baseUrl}${config.documentEndpoint}?${queryParams}`
+		: `${config.baseUrl}${config.documentEndpoint}`;
+
+	// Return ready-to-use request object
+	return new Request(url, {
+		headers: {
+			Authorization: `Basic ${encodedCredentials}`,
+			accept: "application/json",
+		},
+	});
+};
+
+/**
+ * Builds a fetch-ready request for downloading a single document
+ * from Paperless.
+ *
+ * Uses Paperless basic authentication and the provided document ID
+ * to construct the download endpoint URL and required headers.
+ *
+ * @param input.config Paperless configuration containing base URL and credentials
+ * @param input.docId  ID of the document to download
+ */
+export const buildPaperlessDownloadRequest = (input: {
+	config: PaperlessClientConfig;
+	docId: string;
+}): Request => {
+	const { config, docId } = input;
+	const { username, password } = config;
+
+	const encodedCredentials = Buffer.from(`${username}:${password}`).toString(
+		"base64",
+	);
+
+	const url = `${config.baseUrl}${config.documentEndpoint}${encodeURIComponent(docId)}/download/`;
+
+	return new Request(url, {
+		headers: {
+			Authorization: `Basic ${encodedCredentials}`,
+			accept: "*/*",
+			"accept-encoding": "identity",
+		},
+	});
+};
+
+export const buildCustomFieldsRequest = (input: {
+	config: PaperlessClientConfig;
+}): Request => {
+	const { config } = input;
+	const { username, password } = config;
+
+	const encodedCredentials = Buffer.from(`${username}:${password}`).toString(
+		"base64",
+	);
+
+	const url = `${config.baseUrl}${config.customFieldsEndpoint}`;
+
+	return new Request(url, {
+		headers: {
+			Authorization: `Basic ${encodedCredentials}`,
+			accept: "application/json",
+		},
+	});
+};
+
+/**
+ * Input args for the mapper that takes params
+ * and builds a query string.
+ */
+interface PaperlessMapperInput {
+	/**
+	 * TableViewParams - The params that the portal-ui/feature/table generates
+	 * from the view.
+	 */
+	params: TableViewParams;
+	/** General document setup for paperlessDoc */
+	paperlessParams: PaperlessDocConfig;
+	tenantField: string;
+	customerId: string;
+	canViewAll: boolean;
+}
+
+// Paperless Query Params
+const pq = {
+	customField: (name: string, value: string) =>
+		`custom_field_query=["${name}", "exact", "${value}"]`,
+	documentType: (type: string) => `document_type__name__iexact=${type}`,
+	param: (key: string, value: string | number) => `${key}=${value}`,
+	search: (column: string, term: string) =>
+		`${column}__icontains=${encodeURIComponent(term)}`,
+};
+
+/**
+ *
+ * Maps our unified Portal params and paperless-specific document settings
+ * to the specific Paperless API syntax.
+ * @param params Query parameters in portal format
+ * @internal
+ */
+const mapParamsToQueryString = ({
+	params,
+	paperlessParams,
+	tenantField,
+	customerId,
+	canViewAll,
+}: PaperlessMapperInput) => {
+	const { type, paperlessToPortalMap } = paperlessParams;
+
+	// Tenant
+	const tenancy = canViewAll ? [] : [pq.customField(tenantField, customerId)];
+
+	// Base
+	const coreParts = [
+		pq.documentType(type),
+		pq.param("page", params.page + 1),
+		pq.param("page_size", params.pageSize),
+	];
+
+	// Search
+	const searchEnabled = params.searchTerm && params.searchColumn;
+	const searchPart = searchEnabled
+		? pq.search(
+				paperlessToPortalMap?.[params.searchColumn] || params.searchColumn,
+				params.searchTerm,
+			)
+		: null;
+
+	// Filters
+	const filtersPart = Object.entries(params?.filters ?? {})
+		.filter(([_, value]) => value !== "all" && typeof value === "string")
+		.map(([name, value]) => pq.customField(name, value as string));
+
+	// Build full URL
+	return [...tenancy, ...coreParts, searchPart, ...filtersPart].join("&");
+};
+
+interface PaperlessResponse {
+	/** an array with all id's of docs */
+	all?: number[];
+	/** Property name from paperless */
+	results: PaperlessDoc[];
+}
+
+export type PaperlessCustomFieldEntry = {
+	field: number;
+	value: unknown;
+	name?: string;
+};
+
+export interface PaperlessDoc {
+	id: string | number;
+	title: string;
+	created_date: string;
+	document_type: string;
+	customer_id: string;
+	custom_fields: PaperlessCustomFieldEntry[];
+}
+
+export type CustomFieldsMap = Record<number, string>;
+
+interface TransformPaperlessResponseInput {
+	paperlessResponse: PaperlessResponse;
+	customFieldsMap: Record<number, string>;
+	transformDoc: (data: PaperlessDoc, cfMap: Record<number, string>) => unknown;
+}
+
+/**
+ * TODO: CREATE ZOD SCHEMA FOR PAPERLESS RESPONSE
+ * TODO:
+ * @param
+ * @returns
+ */
+export const transformPaperlessResponse = ({
+	paperlessResponse: { results, all },
+	customFieldsMap,
+	transformDoc,
+}: TransformPaperlessResponseInput) => ({
+	data: results.map((doc) => transformDoc(doc, customFieldsMap)),
+	items: all?.length || results.length,
+});

package/src/paperless/config.ts

@@ -0,0 +1,31 @@
+import type { PaperlessClientConfig } from "./client";
+
+const PAPERLESS_ENDPOINT = "/api/documents/" as const;
+const TENANT_FIELD = "customer_id" as const;
+const CUSTOM_FIELDS_ENDPOINT = "/api/custom_fields/" as const;
+
+export const createPaperlessConfig = (input: {
+	username: string;
+	password: string;
+	baseUrl: string;
+	documentEndpoint?: string;
+	tenantField?: string;
+	customFieldsEndpoint?: string;
+}): PaperlessClientConfig => {
+	const baseUrl = input.baseUrl.trim();
+
+	return {
+		username: input.username,
+		password: input.password,
+		baseUrl,
+		documentEndpoint: input.documentEndpoint ?? PAPERLESS_ENDPOINT,
+		tenantField: input.tenantField ?? TENANT_FIELD,
+		customFieldsEndpoint: input.customFieldsEndpoint ?? CUSTOM_FIELDS_ENDPOINT,
+	};
+};
+
+export const createPaperlessAssets = (input?: { logoUrl?: string }) => {
+	return {
+		logoUrl: input?.logoUrl ?? "paperless-logo.png",
+	};
+};

package/tsconfig.json

@@ -0,0 +1,28 @@
+{
+	"compilerOptions": {
+		"target": "ES6",
+		"useDefineForClassFields": true,
+		"lib": ["ES2022", "DOM", "DOM.Iterable"],
+		"module": "ESNext",
+		"moduleResolution": "bundler",
+		"sourceMap": true,
+		"esModuleInterop": true,
+		"skipLibCheck": true,
+		"declaration": true,
+		"preserveSymlinks": true,
+		"resolveJsonModule": true,
+		"isolatedModules": true,
+		"emitDeclarationOnly": true,
+		"jsx": "preserve",
+		"strict": true,
+		"noUnusedLocals": true,
+		"noUnusedParameters": true,
+		"noFallthroughCasesInSwitch": true,
+		"allowJs": true,
+		"forceConsistentCasingInFileNames": true,
+		"incremental": true,
+		"rootDir": "./src",
+		"outDir": "./dist"
+	},
+	"include": ["src"]
+}