@managemint-solutions/sdk 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# ManageMint Solutions SDK
+
+Typed Supabase data-access SDK for ManageMint Solutions. Query logic and the generated
+database types live here; consumers (api, portal) get typed responses with no casts.
+
+## Install
+
+```bash
+npm install @managemint-solutions/sdk @supabase/supabase-js
+```
+
+`@supabase/supabase-js` (^2.103.0), `class-validator` (^0.15) and `class-transformer` (^0.5)
+are peer dependencies — the request DTOs (`AddStatusDto`, `UpdateStatusDto`, `StatusIdDto`,
+`GetStatusesDto`) ship with their class-validator decorators so consumers validate against
+the same rules the SDK's input types describe. `@nestjs/common` (^11) is an optional peer
+dependency, needed only for the `@managemint-solutions/sdk/nest` subpath.
+
+## Usage
+
+```ts
+import { createSupabaseClient, isPostgrestError } from '@managemint-solutions/sdk';
+import type { StatusEntity } from '@managemint-solutions/entities/status';
+import { StatusEntityTypes } from '@managemint-solutions/entities/status/enum';
+
+const supabase = createSupabaseClient({
+  url: process.env.SUPABASE_URL!,
+  key: process.env.SUPABASE_PUBLISHABLE_KEY!, // queries run under the caller's RLS
+  accessToken: userJwt,
+});
+
+// Inputs and outputs are the shared types from @managemint-solutions/entities.
+const statuses: StatusEntity[] = await supabase.statuses.list(StatusEntityTypes.PROJECT);
+const created = await supabase.statuses.create({
+  label: 'In progress',
+  colour: '#2ecc71',
+  entity: StatusEntityTypes.PROJECT,
+});
+await supabase.statuses.update(created.mms_id, { label: 'Doing', colour: '#2ecc71' });
+await supabase.statuses.remove(created.mms_id);
+```
+
+The client decodes `{ mms_id, organization_id }` from the JWT itself and scopes every query
+by `organization_id`. `supabase.supabase` is the raw typed `@supabase/supabase-js` client
+(`TypedSupabaseClient`) — the escape hatch for queries not yet covered by a resource.
+
+## Errors
+
+Every error the SDK throws is a `SupabaseClientError` carrying the HTTP `status` to respond
+with and the client-facing body, `toResponse()` → `{ error, message }`. Postgrest/Postgres
+errors are translated by `mapPostgrestError` (Postgrest code → status, RLS permission and
+module denials → readable messages); JWT problems are `401 Authentication Error`. Consumers
+return these as-is instead of mapping database errors themselves.
+
+## NestJS
+
+```ts
+import { SupabaseUserClient } from '@managemint-solutions/sdk/nest';
+import { GetStatusesDto, SupabaseClient } from '@managemint-solutions/sdk';
+
+@Controller('statuses')
+export class StatusesController {
+  @Get(':entity')
+  getStatuses(@SupabaseUserClient() supabase: SupabaseClient, @Param() params: GetStatusesDto) {
+    return supabase.statuses.list(params.entity);
+  }
+}
+```
+
+The decorator builds a per-request client from the request's `Bearer` token plus the
+`SUPABASE_URL` and `SUPABASE_PUBLISHABLE_KEY` environment variables. A missing or
+malformed token becomes an `UnauthorizedException`. The DTOs work with Nest's global
+`ValidationPipe` as-is (`whitelist`, `forbidNonWhitelisted`, `transform`).
+
+`toHttpException(error)` converts a `SupabaseClientError` into an `HttpException` with the
+same status and body — call it from your global exception filter so services can let SDK
+errors propagate without any try/catch.
+
+## Development
+
+```bash
+npm install
+npm test        # jest + ts-jest; specs live in src/<resource>/tests/*.spec.ts
+npm run build   # tsc -p tsconfig.build.json (excludes specs), CommonJS output in dist/ — the type gate
+```
+
+`src/database.types.ts` is generated by `supabase gen types typescript` and is committed
+here; regenerating it produces a reviewable diff and requires a version bump.
+Publishing happens on push to `main` via `.github/workflows/release.yml`.

package/dist/auth.d.ts

@@ -0,0 +1,5 @@
+export type AuthContext = {
+    mms_id: string;
+    organization_id: string;
+};
+export declare const decodeAuthContext: (accessToken: string) => AuthContext;

package/dist/auth.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeAuthContext = void 0;
+const errors_1 = require("./errors");
+const authError = (message) => new errors_1.SupabaseClientError({ status: 401, error: 'Authentication Error', message });
+const decodeBase64Url = (segment) => typeof Buffer !== 'undefined'
+    ? Buffer.from(segment, 'base64url').toString('utf8')
+    : atob(segment.replace(/-/g, '+').replace(/_/g, '/')); // browser (portal later)
+const decodeAuthContext = (accessToken) => {
+    const parts = accessToken.split('.');
+    if (parts.length !== 3)
+        throw authError('Malformed JWT');
+    let payload;
+    try {
+        payload = JSON.parse(decodeBase64Url(parts[1]));
+    }
+    catch {
+        throw authError('Invalid JWT payload');
+    }
+    const mms_id = payload.sub;
+    const organization_id = payload.user_metadata?.organization_id;
+    if (typeof mms_id !== 'string' ||
+        typeof organization_id !== 'string' ||
+        organization_id.trim() === '') {
+        throw authError('JWT is missing mms_id/organization_id claims');
+    }
+    return { mms_id, organization_id };
+};
+exports.decodeAuthContext = decodeAuthContext;
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":";;;AAAA,qCAA+C;AAI/C,MAAM,SAAS,GAAG,CAAC,OAAe,EAAuB,EAAE,CACzD,IAAI,4BAAmB,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,sBAAsB,EAAE,OAAO,EAAE,CAAC,CAAC;AAEnF,MAAM,eAAe,GAAG,CAAC,OAAe,EAAU,EAAE,CAClD,OAAO,MAAM,KAAK,WAAW;IAC3B,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC;IACpD,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CAAC,CAAC,yBAAyB;AAE7E,MAAM,iBAAiB,GAAG,CAAC,WAAmB,EAAe,EAAE;IACpE,MAAM,KAAK,GAAG,WAAW,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,SAAS,CAAC,eAAe,CAAC,CAAC;IAEzD,IAAI,OAAyE,CAAC;IAC9E,IAAI,CAAC;QACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAClD,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,SAAS,CAAC,qBAAqB,CAAC,CAAC;IACzC,CAAC;IAED,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAC3B,MAAM,eAAe,GAAG,OAAO,CAAC,aAAa,EAAE,eAAe,CAAC;IAC/D,IACE,OAAO,MAAM,KAAK,QAAQ;QAC1B,OAAO,eAAe,KAAK,QAAQ;QACnC,eAAe,CAAC,IAAI,EAAE,KAAK,EAAE,EAC7B,CAAC;QACD,MAAM,SAAS,CAAC,8CAA8C,CAAC,CAAC;IAClE,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC;AACrC,CAAC,CAAC;AAtBW,QAAA,iBAAiB,qBAsB5B"}

package/dist/client.d.ts

@@ -0,0 +1,17 @@
+import { type SupabaseClient as SupabaseJsClient } from '@supabase/supabase-js';
+import type { Database } from './database.types';
+import { type AuthContext } from './auth';
+import { StatusesResource } from './statuses';
+export type TypedSupabaseClient = SupabaseJsClient<Database>;
+export type SupabaseClientConfig = {
+    url: string;
+    key: string;
+    accessToken: string;
+};
+export declare class SupabaseClient {
+    readonly supabase: TypedSupabaseClient;
+    readonly auth: AuthContext;
+    readonly statuses: StatusesResource;
+    constructor(config: SupabaseClientConfig);
+}
+export declare const createSupabaseClient: (config: SupabaseClientConfig) => SupabaseClient;

package/dist/client.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSupabaseClient = exports.SupabaseClient = void 0;
+const supabase_js_1 = require("@supabase/supabase-js");
+const auth_1 = require("./auth");
+const statuses_1 = require("./statuses");
+class SupabaseClient {
+    supabase; // escape hatch for not-yet-migrated queries
+    auth;
+    statuses;
+    constructor(config) {
+        this.auth = (0, auth_1.decodeAuthContext)(config.accessToken);
+        this.supabase = (0, supabase_js_1.createClient)(config.url, config.key, {
+            global: { headers: { Authorization: `Bearer ${config.accessToken}` } },
+            auth: { persistSession: false, autoRefreshToken: false },
+        });
+        this.statuses = new statuses_1.StatusesResource(this.supabase, this.auth);
+    }
+}
+exports.SupabaseClient = SupabaseClient;
+const createSupabaseClient = (config) => new SupabaseClient(config);
+exports.createSupabaseClient = createSupabaseClient;
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":";;;AAAA,uDAA8F;AAE9F,iCAA6D;AAC7D,yCAA8C;AAU9C,MAAa,cAAc;IAChB,QAAQ,CAAsB,CAAC,4CAA4C;IAC3E,IAAI,CAAc;IAClB,QAAQ,CAAmB;IAEpC,YAAY,MAA4B;QACtC,IAAI,CAAC,IAAI,GAAG,IAAA,wBAAiB,EAAC,MAAM,CAAC,WAAW,CAAC,CAAC;QAClD,IAAI,CAAC,QAAQ,GAAG,IAAA,0BAAY,EAAW,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE;YAC7D,MAAM,EAAE,EAAE,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,MAAM,CAAC,WAAW,EAAE,EAAE,EAAE;YACtE,IAAI,EAAE,EAAE,cAAc,EAAE,KAAK,EAAE,gBAAgB,EAAE,KAAK,EAAE;SACzD,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,GAAG,IAAI,2BAAgB,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;IACjE,CAAC;CACF;AAbD,wCAaC;AAEM,MAAM,oBAAoB,GAAG,CAAC,MAA4B,EAAkB,EAAE,CACnF,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;AADhB,QAAA,oBAAoB,wBACJ"}