@nexpress/core 0.1.0

package/dist/index-CeiTvwbp.d.ts

@@ -0,0 +1,168 @@
+import { i as NpFindResult, H as NpImageSize, j as NpFieldConfig } from './types-TlsbXS0T.js';
+import { and } from 'drizzle-orm';
+import { PgTable } from 'drizzle-orm/pg-core';
+import { ReadableStream } from 'node:stream/web';
+
+interface NpFileMetadata {
+    contentType: string;
+    contentLength: number;
+    originalFilename: string;
+}
+interface NpStorageAdapter {
+    upload(key: string, data: Buffer | ReadableStream, metadata: NpFileMetadata): Promise<void>;
+    getStream(key: string): Promise<ReadableStream>;
+    getUrl(key: string): Promise<string>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+}
+
+declare function setStorageAdapter(adapter: NpStorageAdapter): void;
+declare function getStorageAdapter(): NpStorageAdapter;
+/**
+ * Polymorphic uploader: a row on `np_media` is owned by exactly
+ * one of staff (`uploadedBy` → `np_users.id`) or member
+ * (`uploadedByMemberId` → `np_members.id`, Phase 9.7j). Pass a
+ * `null` value as the second argument to `uploadMedia` for plugin /
+ * system uploads with no human owner — both columns stay null and
+ * the audit log carries the actor.
+ */
+type NpMediaUploader = {
+    kind: "staff";
+    userId: string;
+} | {
+    kind: "member";
+    memberId: string;
+} | null;
+declare function uploadMedia(file: {
+    buffer: Buffer;
+    originalFilename: string;
+    mimeType: string;
+}, uploader: NpMediaUploader | string, folderId?: string): Promise<{
+    id: string;
+    status: string;
+}>;
+declare function processMediaImage(mediaId: string, config: {
+    sizes?: NpImageSize[];
+    format?: string;
+    quality?: number;
+}): Promise<void>;
+declare function getMediaById(id: string): Promise<Record<string, unknown> | null>;
+declare function deleteMedia(id: string): Promise<{
+    deleted: boolean;
+    references?: unknown[];
+}>;
+/**
+ * Phase 9.7k uploader filters. `uploaderKind` partitions the
+ * library into staff-uploaded rows (`uploaded_by IS NOT NULL`) vs
+ * member-uploaded rows (`uploaded_by_member_id IS NOT NULL`) — the
+ * two columns are mutually exclusive on every row written through
+ * `uploadMedia`. `uploadedByMemberId` narrows to a specific member
+ * for "show me everything @handle uploaded" investigations after a
+ * spam wave.
+ */
+type NpMediaUploaderKindFilter = "staff" | "member";
+declare function listMedia(options: {
+    page?: number;
+    limit?: number;
+    folderId?: string;
+    mimeType?: string;
+    uploaderKind?: NpMediaUploaderKindFilter;
+    uploadedByMemberId?: string;
+    /**
+     * Substring match against `filename` and `alt`. Matches
+     * server-side via `ILIKE`, so the page-builder block-image
+     * picker can search the whole library without paging through
+     * every result client-side. Empty / whitespace-only `q` is
+     * treated as no filter.
+     */
+    q?: string;
+}): Promise<NpFindResult>;
+declare function cleanupDeletedMedia(olderThanDays: number): Promise<number>;
+
+interface NpProcessedImageVariant {
+    name: string;
+    buffer: Buffer;
+    width: number;
+    height: number;
+    size: number;
+}
+interface NpProcessedImageSourceMetadata {
+    width: number | null;
+    height: number | null;
+    format: string | null;
+}
+interface NpProcessedImageResult {
+    source: NpProcessedImageSourceMetadata;
+    variants: NpProcessedImageVariant[];
+}
+declare const DEFAULT_IMAGE_SIZES: NpImageSize[];
+declare function processImage(inputBuffer: Buffer, sizes: NpImageSize[], options?: {
+    format?: string;
+    quality?: number;
+}): Promise<NpProcessedImageResult>;
+
+interface InsertValuesQuery extends Promise<unknown> {
+    returning(): Promise<unknown[]>;
+}
+interface SelectQuery extends Promise<unknown[]> {
+    where(condition: ReturnType<typeof and>): SelectQuery;
+}
+interface DrizzleTransactionLike {
+    insert(table: PgTable): {
+        values(values: Record<string, unknown> | Record<string, unknown>[]): InsertValuesQuery;
+    };
+    delete(table: PgTable): {
+        where(condition: ReturnType<typeof and>): Promise<unknown>;
+    };
+    select(selection?: Record<string, unknown>): {
+        from(table: PgTable): SelectQuery;
+    };
+}
+declare function extractMediaIds(fields: NpFieldConfig[], data: Record<string, unknown>): Array<{
+    mediaId: string;
+    field: string;
+}>;
+declare function syncMediaRefs(tx: DrizzleTransactionLike, collection: string, documentId: string, refs: Array<{
+    mediaId: string;
+    field: string;
+}>): Promise<void>;
+
+/**
+ * Built-in image variants. Plugin-defined custom variants are
+ * accepted as plain strings — the lookup walks `media.sizes`
+ * regardless of whether the variant was named in this union.
+ */
+type NpMediaVariantName = "original" | "thumbnail" | "small" | "medium" | "large" | "xlarge" | "og" | (string & {});
+interface NpGetMediaUrlOptions {
+    /**
+     * Which size to resolve. Defaults to `"original"` — the bytes
+     * uploaded by the user. Sized variants (`thumbnail`, `medium`,
+     * `og`, …) are only present for processed images; non-image
+     * media has only `"original"`.
+     */
+    variant?: NpMediaVariantName;
+    /**
+     * When `true` (default) and the requested variant doesn't
+     * exist on the media row, fall back to the original. Set to
+     * `false` to get `null` instead — useful when you'd rather
+     * skip rendering than serve a 5 MB original where a thumbnail
+     * was expected.
+     */
+    fallbackToOriginal?: boolean;
+}
+/**
+ * Resolve a media record's public URL via the active storage
+ * adapter — works the same for local-disk and S3 deployments,
+ * and uses the URL cached on the size record when present
+ * (avoids a redundant `presign` round-trip for S3).
+ *
+ * Returns `null` when:
+ *  - the media id doesn't exist (or was soft-deleted),
+ *  - the requested variant isn't available AND
+ *    `fallbackToOriginal: false` was passed.
+ *
+ * Pure read — no side effects, safe to call from RSC.
+ */
+declare function getMediaUrl(id: string, options?: NpGetMediaUrlOptions): Promise<string | null>;
+
+export { DEFAULT_IMAGE_SIZES as D, type NpStorageAdapter as N, type NpFileMetadata as a, type NpGetMediaUrlOptions as b, type NpMediaUploader as c, type NpMediaUploaderKindFilter as d, type NpMediaVariantName as e, type NpProcessedImageResult as f, type NpProcessedImageVariant as g, cleanupDeletedMedia as h, deleteMedia as i, extractMediaIds as j, getMediaById as k, getMediaUrl as l, getStorageAdapter as m, listMedia as n, processMediaImage as o, processImage as p, type DrizzleTransactionLike as q, type NpProcessedImageSourceMetadata as r, setStorageAdapter as s, syncMediaRefs as t, uploadMedia as u };

package/dist/index-XwP1ET8b.d.ts

@@ -0,0 +1,61 @@
+import * as drizzle_orm_node_postgres from 'drizzle-orm/node-postgres';
+import { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import { Pool } from 'pg';
+import { V as schema } from './index-CY55LC0u.js';
+import { d as NpCollectionConfig } from './types-TlsbXS0T.js';
+
+declare function setDb(db: NodePgDatabase<Record<string, unknown>>): void;
+declare function getDb(): NodePgDatabase<Record<string, unknown>>;
+
+interface CreateDbConnectionConfig {
+    connectionString: string;
+    pool?: Pool;
+    /**
+     * Override Pool option defaults. Useful for tests, or for sites that need
+     * to tune connection limits / timeouts. The fields explicitly set below
+     * (`connectionTimeoutMillis`, `statement_timeout`) win unless callers
+     * override them here.
+     */
+    poolOptions?: ConstructorParameters<typeof Pool>[0];
+}
+declare function createDbConnection(config: CreateDbConnectionConfig): drizzle_orm_node_postgres.NodePgDatabase<typeof schema> & {
+    $client: Pool;
+};
+
+interface GenerateDrizzleSchemaOptions {
+    /**
+     * Module specifier to import the core schema tables (npUsers, npMedia) from.
+     * Defaults to "@nexpress/core". Override when the consumer's tooling
+     * (e.g. drizzle-kit's CJS resolver) can't load the core package via its
+     * exports map — point at a relative path to core's source in that case.
+     */
+    schemaImport?: string;
+}
+declare function generateDrizzleSchema(collections: NpCollectionConfig[], options?: GenerateDrizzleSchemaOptions): string;
+
+declare function generateTypeScript(collections: NpCollectionConfig[]): string;
+/**
+ * Renders a complete `documents.ts` module: imports from
+ * `@nexpress/core`, per-collection `${Pascal}Document` interfaces,
+ * and typed read-helper wrappers (`find${Pascal}` /
+ * `get${Pascal}Document`) that bind the type generic so call sites
+ * don't have to.
+ *
+ * Collections with hasMany relationship fields get a smarter
+ * wrapper: when the caller's `where` clause names a hasMany
+ * field, the wrapper queries the join table for matching parent
+ * ids first, intersects across multiple hasMany filters, and
+ * delegates to `findDocuments` with `id: idList`. That covers
+ * the friction surfaced in #540's category-page dogfood — a
+ * `where: { categories: id }` filter looked typed but failed at
+ * runtime because `categories` isn't a column on the parent
+ * table; this wrapper makes it work.
+ *
+ * The output is meant for `apps/<app>/src/db/generated/documents.ts`
+ * and is a direct counterpart to `generateDrizzleSchema`'s
+ * `collections.ts` (Drizzle schema). Both files come from the same
+ * `nexpressConfig.collections` source so they stay in sync.
+ */
+declare function generateDocumentsModule(collections: NpCollectionConfig[]): string;
+
+export { type CreateDbConnectionConfig as C, generateDrizzleSchema as a, generateTypeScript as b, createDbConnection as c, getDb as d, generateDocumentsModule as g, setDb as s };