@fakeware/plugin-pickware 0.0.1

package/README.md

@@ -0,0 +1,140 @@
+# @fakeware/plugin-pickware
+
+A [fakeware](https://github.com/fakeware-sh/fakeware) plugin for **Pickware ERP** —
+seed warehouses, bin locations, and stock into a Shopware 6 shop running Pickware.
+
+It teaches fakeware about Pickware's DAL entities so you can author them with
+`define(...)` in your data files, and contributes a fetcher that loads the shop's
+existing warehouses into the run context.
+
+> **Status: minimal v1.** Covers `pickware_erp_warehouse`, `pickware_erp_bin_location`,
+> and `pickware_erp_stock_movement`. Suppliers, purchasing, stocktakes, and the
+> WMS/POS/Shipping entities are intentionally out of scope for now.
+
+## Install
+
+```sh
+bun add -D @fakeware/plugin-pickware
+# @fakeware/core is a peer dependency — your fakeware project already has it.
+```
+
+## Usage
+
+Register the plugin in `fakeware.config.ts`:
+
+```ts
+import { defineConfig } from '@fakeware/core/config'
+import { pickware } from '@fakeware/plugin-pickware'
+
+export default defineConfig({
+  shopware: {
+    url: process.env.SHOPWARE_URL!,
+    clientId: process.env.SHOPWARE_CLIENT_ID!,
+    clientSecret: process.env.SHOPWARE_CLIENT_SECRET!,
+  },
+  plugins: [pickware()],
+})
+```
+
+Author Pickware data in `data/*.ts`. Importing the package augments fakeware's
+`EntityRegistry`, so the `pickware_erp_*` entity names are fully type-checked:
+
+`data/pickware.ts`:
+
+```ts
+import { define, ref } from '@fakeware/core'
+import { stockMovementIn } from '@fakeware/plugin-pickware'
+
+define('pickware_erp_warehouse', { $key: 'main', name: 'Main', code: 'WH-01' })
+
+define('pickware_erp_bin_location', {
+  $key: 'a1',
+  code: 'A1',
+  warehouseId: ref('pickware_erp_warehouse/main'),
+})
+
+define(
+  'pickware_erp_stock_movement',
+  stockMovementIn({
+    productId: ref('product/my-product'),
+    warehouseId: ref('pickware_erp_warehouse/main'),
+    quantity: 100,
+  }),
+)
+```
+
+Bin locations referencing a warehouse via `ref()` are written after it
+automatically. Seed stock through `pickware_erp_stock_movement` (an append-only
+ledger) — never write `product.stock` directly while Pickware is active.
+
+Run it with the fakeware CLI:
+
+```sh
+fakeware up --dry-run
+fakeware up
+```
+
+### Referencing existing warehouses
+
+`pickware()` adds a fetcher that loads the shop's current warehouses into the run
+context. Read them in a plugin `setup` hook or any code with access to the context:
+
+```ts
+import { pickwareWarehouses } from '@fakeware/plugin-pickware'
+
+const existing = pickwareWarehouses(shopContext.extensions)
+const main = existing.find((w) => w.code === 'WH-01')
+```
+
+## ⚠️ Verify field names against your install
+
+Pickware publishes **no Shopware 6 API documentation**, so the entity *field
+names* in this plugin (especially `destinationWarehouseId` on the stock movement)
+are best-effort. **Before a live `up`, confirm them against your shop:**
+
+```sh
+curl -H "Authorization: Bearer <token>" \
+  https://your-shop.example/api/_info/entity-schema.json \
+  | jq 'keys | map(select(startswith("pickware_erp")))'
+```
+
+Inspect the `pickware_erp_warehouse`, `pickware_erp_bin_location`, and
+`pickware_erp_stock_movement` field definitions there (or watch the Pickware
+admin module's network requests) and adjust the record shapes in
+`src/entities.ts` / the `stockMovementIn` helper to match.
+
+Key facts the plugin is built around:
+
+- Stock is owned by Pickware's **append-only ledger** (`pickware_erp_stock_movement`).
+  You change stock by **adding movements**; Pickware recomputes
+  `pickware_erp_stock` and mirrors the total back into `product.stock`.
+- Writing `product.stock` directly via the standard API while Pickware is active
+  **nulls** the Pickware warehouses — don't do it.
+
+## Publishing
+
+This repo publishes `@fakeware/plugin-pickware` to npm via
+[release-please](https://github.com/googleapis/release-please) — the same flow as
+the fakeware monorepo. Conventional commits on `main` open a release PR; merging
+it tags a version and publishes.
+
+**One-time repo setup** (in GitHub → Settings):
+
+- Add an npm publish credential for the `@fakeware` scope. The release workflow
+  uses npm provenance (`id-token: write`) — configure a trusted publisher on npm,
+  or add an `NPM_TOKEN` secret and wire it into `.github/workflows/release.yml`.
+- The default `GITHUB_TOKEN` is sufficient for release-please's PR/tagging.
+
+## Development
+
+```sh
+bun install
+bun run build
+bun run typecheck
+bun test
+bun run check
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,52 @@
+import { FakewarePlugin, ShopContextFetcher } from "@fakeware/core";
+
+//#region src/entities.d.ts
+interface PickwareWarehouseRecord {
+  $key?: string;
+  name: string;
+  code: string;
+}
+interface PickwareBinLocationRecord {
+  $key?: string;
+  code: string;
+  warehouseId: string;
+}
+interface PickwareStockMovementRecord {
+  $key?: string;
+  productId: string;
+  quantity: number;
+  destinationWarehouseId: string;
+}
+declare module '@fakeware/core' {
+  interface EntityRegistry {
+    pickware_erp_warehouse: PickwareWarehouseRecord;
+    pickware_erp_bin_location: PickwareBinLocationRecord;
+    pickware_erp_stock_movement: PickwareStockMovementRecord;
+  }
+}
+//#endregion
+//#region src/fetchers.d.ts
+interface PickwareWarehouseRow {
+  id: string;
+  name?: string;
+  code?: string;
+  [key: string]: unknown;
+}
+declare const PICKWARE_WAREHOUSES_KEY = "pickwareWarehouses";
+declare function pickwareWarehouses(extensions: Record<string, unknown>): PickwareWarehouseRow[];
+declare const warehousesFetcher: ShopContextFetcher;
+//#endregion
+//#region src/helpers.d.ts
+interface StockMovementInInput {
+  productId: string;
+  warehouseId: string;
+  quantity: number;
+  $key?: string;
+}
+declare function stockMovementIn(input: StockMovementInInput): PickwareStockMovementRecord;
+//#endregion
+//#region src/plugin.d.ts
+declare function pickware(): FakewarePlugin;
+//#endregion
+export { PICKWARE_WAREHOUSES_KEY, type PickwareBinLocationRecord, type PickwareStockMovementRecord, type PickwareWarehouseRecord, type PickwareWarehouseRow, type StockMovementInInput, pickware, pickwareWarehouses, stockMovementIn, warehousesFetcher };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,37 @@
+import { definePlugin } from "@fakeware/core";
+//#region src/fetchers.ts
+const PICKWARE_WAREHOUSES_KEY = "pickwareWarehouses";
+function pickwareWarehouses(extensions) {
+	return extensions["pickwareWarehouses"] ?? [];
+}
+const warehousesFetcher = {
+	entity: "pickware warehouses",
+	fetch: (client) => client.invoke("post /search/pickware-erp-warehouse", { body: { limit: 500 } }),
+	merge: (data, raw) => {
+		const rows = raw?.data ?? [];
+		data.extensions[PICKWARE_WAREHOUSES_KEY] = rows;
+	}
+};
+//#endregion
+//#region src/helpers.ts
+function stockMovementIn(input) {
+	if (!Number.isFinite(input.quantity) || input.quantity <= 0) throw new Error(`stockMovementIn: quantity must be a positive number, got ${input.quantity}.`);
+	return {
+		...input.$key ? { $key: input.$key } : {},
+		productId: input.productId,
+		quantity: input.quantity,
+		destinationWarehouseId: input.warehouseId
+	};
+}
+//#endregion
+//#region src/plugin.ts
+function pickware() {
+	return definePlugin({
+		name: "pickware",
+		fetchers: [warehousesFetcher]
+	});
+}
+//#endregion
+export { PICKWARE_WAREHOUSES_KEY, pickware, pickwareWarehouses, stockMovementIn, warehousesFetcher };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/fetchers.ts","../src/helpers.ts","../src/plugin.ts"],"sourcesContent":["import type { ShopContextFetcher } from '@fakeware/core'\n\nexport interface PickwareWarehouseRow {\n  id: string\n  name?: string\n  code?: string\n  [key: string]: unknown\n}\n\nexport const PICKWARE_WAREHOUSES_KEY = 'pickwareWarehouses'\n\nexport function pickwareWarehouses(extensions: Record<string, unknown>): PickwareWarehouseRow[] {\n  return (extensions[PICKWARE_WAREHOUSES_KEY] as PickwareWarehouseRow[] | undefined) ?? []\n}\n\nexport const warehousesFetcher: ShopContextFetcher = {\n  entity: 'pickware warehouses',\n  fetch: (client) =>\n    (client.invoke as (path: string, params: unknown) => Promise<unknown>)(\n      'post /search/pickware-erp-warehouse',\n      { body: { limit: 500 } },\n    ),\n  merge: (data, raw) => {\n    const rows = (raw as { data?: PickwareWarehouseRow[] } | null)?.data ?? []\n    data.extensions[PICKWARE_WAREHOUSES_KEY] = rows\n  },\n}\n","import type { PickwareStockMovementRecord } from './entities'\n\nexport interface StockMovementInInput {\n  productId: string\n  warehouseId: string\n  quantity: number\n  $key?: string\n}\n\nexport function stockMovementIn(input: StockMovementInInput): PickwareStockMovementRecord {\n  if (!Number.isFinite(input.quantity) || input.quantity <= 0) {\n    throw new Error(`stockMovementIn: quantity must be a positive number, got ${input.quantity}.`)\n  }\n  return {\n    ...(input.$key ? { $key: input.$key } : {}),\n    productId: input.productId,\n    quantity: input.quantity,\n    destinationWarehouseId: input.warehouseId,\n  }\n}\n","import { definePlugin, type FakewarePlugin } from '@fakeware/core'\nimport { warehousesFetcher } from './fetchers'\n\nexport function pickware(): FakewarePlugin {\n  return definePlugin({\n    name: 'pickware',\n    fetchers: [warehousesFetcher],\n  })\n}\n"],"mappings":";;AASA,MAAa,0BAA0B;AAEvC,SAAgB,mBAAmB,YAA6D;CAC9F,OAAQ,WAAA,yBAA8E,CAAC;AACzF;AAEA,MAAa,oBAAwC;CACnD,QAAQ;CACR,QAAQ,WACL,OAAO,OACN,uCACA,EAAE,MAAM,EAAE,OAAO,IAAI,EAAE,CACzB;CACF,QAAQ,MAAM,QAAQ;EACpB,MAAM,OAAQ,KAAkD,QAAQ,CAAC;EACzE,KAAK,WAAW,2BAA2B;CAC7C;AACF;;;ACjBA,SAAgB,gBAAgB,OAA0D;CACxF,IAAI,CAAC,OAAO,SAAS,MAAM,QAAQ,KAAK,MAAM,YAAY,GACxD,MAAM,IAAI,MAAM,4DAA4D,MAAM,SAAS,EAAE;CAE/F,OAAO;EACL,GAAI,MAAM,OAAO,EAAE,MAAM,MAAM,KAAK,IAAI,CAAC;EACzC,WAAW,MAAM;EACjB,UAAU,MAAM;EAChB,wBAAwB,MAAM;CAChC;AACF;;;AChBA,SAAgB,WAA2B;CACzC,OAAO,aAAa;EAClB,MAAM;EACN,UAAU,CAAC,iBAAiB;CAC9B,CAAC;AACH"}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@fakeware/plugin-pickware",
+  "version": "0.0.1",
+  "description": "Pickware ERP plugin for fakeware. Seed warehouses, bin locations and stock into a Shopware 6 shop running Pickware",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fakeware-sh/plugin-pickware.git"
+  },
+  "keywords": [
+    "fakeware",
+    "fakeware-plugin",
+    "shopware",
+    "pickware",
+    "seed",
+    "fixtures"
+  ],
+  "engines": {
+    "node": ">=20",
+    "bun": ">=1.3.14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "scripts": {
+    "dev": "tsdown --watch",
+    "build": "tsdown",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "check": "biome check . && bun run typecheck",
+    "fix": "biome check . --write && bun run typecheck",
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "@fakeware/core": ">=0.0.9"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.16",
+    "@fakeware/core": "0.0.9",
+    "@types/bun": "1.3.14",
+    "publint": "0.3.21",
+    "tsdown": "^0.22.2",
+    "typescript": "^6.0.3"
+  }
+}