target-supabase-sdk 0.2.0 → 0.2.2

package/src/core.interface.ts

@@ -1,76 +1,77 @@
-import { PostgrestError } from "@supabase/supabase-js";
+import type { PostgrestError } from "@supabase/supabase-js";
 
 export interface Target {
-  id: string;
-  category: string;
-  name: string;
-  value: string;
-  tagList: string[];
-  extra?: string;
-  details?: unknown;
-  created_at: string;
+    id: string;
+    category: string;
+    name: string;
+    value: string;
+    tagList: string[];
+    extra?: string;
+    details?: unknown;
+    created_at: string;
 }
 
-export type TargetPayload<T extends Target> = Omit<T, "id" | "created_at">;
+/** Target row before persistence — no `id` or `created_at`. */
+export type TargetDraft<T extends Target> = Omit<T, "id" | "created_at">;
 
 export enum StatusCode {
-  SUCCESS = 200,
-  ERROR = 400,
+    SUCCESS = 200,
+    ERROR = 400,
 }
 
 export interface SupabaseResponse<T = unknown> {
-  status_code: StatusCode;
-  success: boolean;
-  message?: string;
-  data?: T;
-  error?: {
-    message: string;
-    code?: string;
-  };
+    status_code: StatusCode;
+    success: boolean;
+    message?: string;
+    data?: T;
+    error?: {
+        message: string;
+        code?: string;
+    };
 }
 
 export const generateResponse = {
-  success<T>(data?: T, message?: string): SupabaseResponse<T> {
-    return {
-      status_code: StatusCode.SUCCESS,
-      success: true,
-      message,
-      data,
-    };
-  },
+    success<T>(data?: T, message?: string): SupabaseResponse<T> {
+        return {
+            status_code: StatusCode.SUCCESS,
+            success: true,
+            message,
+            data,
+        };
+    },
 
-  error(
-    message: string | { key: string; error: PostgrestError } | { key: string; error: string },
-    statusCode?: StatusCode,
-    code?: string
-  ): SupabaseResponse {
-    if (typeof message === "string") {
-      return {
-        status_code: statusCode ?? StatusCode.ERROR,
-        success: false,
-        error: {
-          message,
-          code,
-        },
-      };
-    }
-    if (typeof message?.error === "string") {
-      return {
-        status_code: statusCode ?? StatusCode.ERROR,
-        success: false,
-        error: {
-          message: `Error from ${message.key}: ${message.error}`,
-          code,
-        },
-      };
-    }
-    return {
-      status_code: statusCode ?? StatusCode.ERROR,
-      success: false,
-      error: {
-        message: `Error from ${message.key}: ${message?.error?.message}`,
-        code,
-      },
-    };
-  },
+    error(
+        message: string | { key: string; error: PostgrestError } | { key: string; error: string },
+        statusCode?: StatusCode,
+        code?: string,
+    ): SupabaseResponse {
+        if (typeof message === "string") {
+            return {
+                status_code: statusCode ?? StatusCode.ERROR,
+                success: false,
+                error: {
+                    message,
+                    code,
+                },
+            };
+        }
+        if (typeof message?.error === "string") {
+            return {
+                status_code: statusCode ?? StatusCode.ERROR,
+                success: false,
+                error: {
+                    message: `Error from ${message.key}: ${message.error}`,
+                    code,
+                },
+            };
+        }
+        return {
+            status_code: statusCode ?? StatusCode.ERROR,
+            success: false,
+            error: {
+                message: `Error from ${message.key}: ${message?.error?.message}`,
+                code,
+            },
+        };
+    },
 };

package/src/core.utils.ts

@@ -2,91 +2,91 @@ import { pick, pickBy } from "lodash-es";
 
 /** True when running in a development build (Vite or Node). Defaults to false for safety. */
 export function isDevEnvironment(): boolean {
-  if (typeof import.meta !== "undefined" && "env" in import.meta) {
-    const env = (import.meta as ImportMeta & { env?: { DEV?: boolean; MODE?: string } }).env;
-    if (env?.DEV === true || env?.MODE === "development") return true;
-    if (env?.DEV === false || env?.MODE === "production") return false;
-  }
-  if (typeof process !== "undefined" && process.env?.NODE_ENV) {
-    return process.env.NODE_ENV !== "production";
-  }
-  return false;
+    if (typeof import.meta !== "undefined" && "env" in import.meta) {
+        const env = (import.meta as ImportMeta & { env?: { DEV?: boolean; MODE?: string } }).env;
+        if (env?.DEV === true || env?.MODE === "development") return true;
+        if (env?.DEV === false || env?.MODE === "production") return false;
+    }
+    if (typeof process !== "undefined" && process.env?.NODE_ENV) {
+        return process.env.NODE_ENV !== "production";
+    }
+    return false;
 }
 
 export function logDev(...args: unknown[]): void {
-  if (isDevEnvironment()) {
-    console.log(...args);
-  }
+    if (isDevEnvironment()) {
+        console.log(...args);
+    }
 }
 
 export function logDevGroup(label: string, fn: () => void): void {
-  if (!isDevEnvironment()) return;
-  console.group(label);
-  try {
-    fn();
-  } finally {
-    console.groupEnd();
-  }
+    if (!isDevEnvironment()) return;
+    console.group(label);
+    try {
+        fn();
+    } finally {
+        console.groupEnd();
+    }
 }
 
 /** Log internal details, then throw a sanitized error safe to expose to callers. */
 export function handleSupabaseError(context: string, error: unknown, publicMessage?: string): never {
-  console.error(`[${context}] failed:`, error);
-  throw new Error(publicMessage ?? `[${context}] Operation failed`);
+    console.error(`[${context}] failed:`, error);
+    throw new Error(publicMessage ?? `[${context}] Operation failed`);
 }
 
 /** Raw payload -> Available data */
 export abstract class BaseValidator<T extends object> {
-  protected requiredFields: (keyof T)[] = [];
-  protected optionalFields: (keyof T)[] = [];
-  protected ignoredFields: (keyof T)[] = [];
-  protected customValidators: ((val: T) => true | string)[] = [];
+    protected requiredFields: (keyof T)[] = [];
+    protected optionalFields: (keyof T)[] = [];
+    protected ignoredFields: (keyof T)[] = [];
+    protected customValidators: ((val: T) => true | string)[] = [];
 
-  addCustomValidator(validator: (val: T) => true | string) {
-    this.customValidators.push(validator);
-    return this;
-  }
+    addCustomValidator(validator: (val: T) => true | string) {
+        this.customValidators.push(validator);
+        return this;
+    }
 
-  protected validateField(field: keyof T, value: unknown): boolean {
-    // TODO now only empty check, later should add type checks
-    return value != null;
-  }
+    protected validateField(_field: keyof T, value: unknown): boolean {
+        // TODO now only empty check, later should add type checks
+        return value != null;
+    }
 
-  validate = (val: T): T => {
-    const errors: string[] = [];
+    validate = (val: T): T => {
+        const errors: string[] = [];
 
-    // Step 1: Check required fields
-    this.requiredFields.forEach((field) => {
-      if (!this.validateField(field, val[field])) {
-        errors.push(`Missing required field: ${String(field)}`);
-      }
-    });
+        // Step 1: Check required fields
+        this.requiredFields.forEach((field) => {
+            if (!this.validateField(field, val[field])) {
+                errors.push(`Missing required field: ${String(field)}`);
+            }
+        });
 
-    // Step 2: Run custom validators
-    this.customValidators.forEach((validator) => {
-      const result = validator(val);
-      if (result !== true) {
-        errors.push(`Custom validation failed ${result}`);
-      }
-    });
+        // Step 2: Run custom validators
+        this.customValidators.forEach((validator) => {
+            const result = validator(val);
+            if (result !== true) {
+                errors.push(`Custom validation failed ${result}`);
+            }
+        });
 
-    if (errors.length > 0) {
-      const errorCount = errors.length;
-      const errorList = errors.map((error, index) => `  ${index + 1}. ${error}`).join("\n");
+        if (errors.length > 0) {
+            const errorCount = errors.length;
+            const errorList = errors.map((error, index) => `  ${index + 1}. ${error}`).join("\n");
 
-      throw new Error(
-        `[${this.constructor.name}] Validation failed (${errorCount} error${errorCount > 1 ? "s" : ""}):\n${errorList}`
-      );
-    }
+            throw new Error(
+                `[${this.constructor.name}] Validation failed (${errorCount} error${errorCount > 1 ? "s" : ""}):\n${errorList}`,
+            );
+        }
 
-    // Step 3: Pick required and optional fields
-    const required = pick(val, this.requiredFields);
-    const optional = pickBy(val, (value, key) => {
-      const typedKey = key as keyof T;
-      return this.optionalFields.includes(typedKey) && value != null;
-    }) as Partial<T>;
-    // TODO ignoredFields
+        // Step 3: Pick required and optional fields
+        const required = pick(val, this.requiredFields);
+        const optional = pickBy(val, (value, key) => {
+            const typedKey = key as keyof T;
+            return this.optionalFields.includes(typedKey) && value != null;
+        }) as Partial<T>;
+        // TODO ignoredFields
 
-    return { ...required, ...optional } as T;
-  };
+        return { ...required, ...optional } as T;
+    };
 }

package/src/idea/idea.interface.ts

@@ -1,4 +1,4 @@
-import { Target } from "../core.interface";
+import type { Target } from "../core.interface";
 
 export enum CategoryIdea {
     OPPORTUNITY = "opportunity",
@@ -17,7 +17,7 @@ export interface IdeaDetails {
     reviewList: string[];
     /** 切入點 */
     point: string;
-};
+}
 
 export enum Market {
     NA = "NA",
@@ -25,4 +25,4 @@ export enum Market {
     JP = "JP",
     CN = "CN",
     TW = "TW",
-};
+}

package/src/link/link.api.ts

@@ -1,43 +1,41 @@
 import { createTarget } from "../core.api";
 import { BaseValidator } from "../core.utils";
-import { Link, LinkDetails } from "./link.interface";
+import type { Link, LinkDetails } from "./link.interface";
 
 export interface PostLinkCreatePayload {
-  name: Link["name"];
-  value: Link["value"];
-  category: Link["category"];
-  details: LinkDetails;
+    name: Link["name"];
+    value: Link["value"];
+    category: Link["category"];
+    details: LinkDetails;
 }
 
 export class PostLinkValidator extends BaseValidator<PostLinkCreatePayload> {
-  protected requiredFields: (keyof PostLinkCreatePayload)[] = ["name", "value", "category", "details"];
-  protected optionalFields: (keyof PostLinkCreatePayload)[] = [];
+    protected requiredFields: (keyof PostLinkCreatePayload)[] = ["name", "value", "category", "details"];
+    protected optionalFields: (keyof PostLinkCreatePayload)[] = [];
 
-  constructor() {
-    super();
-    // Add custom
-    this.addCustomValidator((val) => {
-      return true;
-    });
-  }
+    constructor() {
+        super();
+        // Add custom
+        this.addCustomValidator((_val) => {
+            return true;
+        });
+    }
 }
 
-
-
 export const postLinkCreate = async (payload: PostLinkCreatePayload) => {
-  return createTarget<Link, PostLinkCreatePayload>({
-    payload: payload,
-    validator: PostLinkValidator,
-    createFn: (validPayload) => {
-      const { name, value, category, details } = validPayload;
+    return createTarget<Link, PostLinkCreatePayload>({
+        payload: payload,
+        validator: PostLinkValidator,
+        createFn: (validPayload) => {
+            const { name, value, category, details } = validPayload;
 
-      return {
-        name,
-        category,
-        value,
-        tagList: [],
-        details,
-      };
-    },
-  });
+            return {
+                name,
+                category,
+                value,
+                tagList: [],
+                details,
+            };
+        },
+    });
 };

package/src/link/link.interface.ts

@@ -1,7 +1,6 @@
-import { Target } from "../core.interface";
+import type { Target } from "../core.interface";
 
 export enum CategoryLink {
-    /** HTML by default */
     LINK = "link",
 }
 
@@ -11,6 +10,7 @@ export interface Link extends Target {
     /** URL */
     value: string;
     details: LinkDetails;
+    /** Only Link can own a custom category, like 'link-log' */
     category: CategoryLink;
 }
 
@@ -22,5 +22,4 @@ export interface LinkDetails {
     /** How to render the link */
     loaderKey: string;
     original: unknown;
-};
-
+}

package/src/list/list.api.ts

@@ -1,43 +1,64 @@
 import { createTarget } from "../core.api";
 import { BaseValidator } from "../core.utils";
-import { List, ListDetails } from "./list.interface";
+import { CategoryList, type List, type ListDetails } from "./list.interface";
 
 export interface PostListCreatePayload {
-  name: List["name"];
-  value: List["value"];
-  category: List["category"];
-  details: ListDetails;
+    name: List["name"];
+    value: List["value"];
+    category: List["category"];
+    details: ListDetails;
 }
 
 export class PostListValidator extends BaseValidator<PostListCreatePayload> {
-  protected requiredFields: (keyof PostListCreatePayload)[] = ["name", "value", "category", "details"];
-  protected optionalFields: (keyof PostListCreatePayload)[] = [];
+    protected requiredFields: (keyof PostListCreatePayload)[] = ["name", "value", "category", "details"];
+    protected optionalFields: (keyof PostListCreatePayload)[] = [];
 
-  constructor() {
-    super();
-    // Add custom
-    this.addCustomValidator((val) => {
-      return true;
-    });
-  }
+    constructor() {
+        super();
+        // Add custom
+        this.addCustomValidator((_val) => {
+            return true;
+        });
+    }
 }
 
+export const postListCreate = async (payload: PostListCreatePayload) => {
+    return createTarget<List, PostListCreatePayload>({
+        payload: payload,
+        validator: PostListValidator,
+        createFn: (validPayload) => {
+            const { name, value, category, details } = validPayload;
 
+            return {
+                name,
+                category,
+                value,
+                tagList: [],
+                details,
+            };
+        },
+    });
+};
 
-export const postListCreate = async (payload: PostListCreatePayload) => {
-  return createTarget<List, PostListCreatePayload>({
-    payload: payload,
-    validator: PostListValidator,
-    createFn: (validPayload) => {
-      const { name, value, category, details } = validPayload;
+/** Log batch create — idempotent on List.value (stable batch hash). */
+export const postLogListCreate = async (payload: PostListCreatePayload) => {
+    return createTarget<List, PostListCreatePayload>({
+        payload,
+        validator: PostListValidator,
+        checkRedundancyFilterList: [
+            { field: "category", operator: "eq", value: CategoryList.LIST },
+            { field: "value", operator: "eq", value: payload.value },
+        ],
+        createFn: (validPayload) => {
+            const { name, value, category, details } = validPayload;
 
-      return {
-        name,
-        category,
-        value,
-        tagList: [],
-        details,
-      };
-    },
-  });
+            return {
+                name,
+                category,
+                value,
+                tagList: [],
+                details,
+            };
+        },
+    });
 };

package/src/list/list.interface.ts

@@ -1,4 +1,4 @@
-import { Target, TargetPayload } from "../core.interface";
+import type { Target } from "../core.interface";
 
 export enum CategoryList {
     LIST = "list",
@@ -19,6 +19,5 @@ export interface ListDetails {
     preview: string;
     /** How to render the List */
     loaderKey: string;
-    items: Array<TargetPayload<Target>>
-};
-
+    items: Array<unknown>;
+}

package/src/node/env/env-parsers.ts

@@ -0,0 +1,77 @@
+import { readEnv } from "./require-env";
+
+export interface EnvIntOptions {
+    env?: NodeJS.ProcessEnv;
+    min?: number;
+    max?: number;
+}
+
+export function envInt(name: string, defaultValue: number, options?: EnvIntOptions): number {
+    const env = options?.env ?? process.env;
+    const raw = readEnv(name, env);
+    if (raw == null) {
+        return defaultValue;
+    }
+
+    const value = Number(raw);
+    if (!Number.isInteger(value)) {
+        throw new Error(`Invalid ${name}: ${raw}`);
+    }
+
+    const min = options?.min;
+    if (min != null && value < min) {
+        throw new Error(`Invalid ${name}: ${raw}`);
+    }
+
+    const max = options?.max;
+    if (max != null && value > max) {
+        throw new Error(`Invalid ${name}: ${raw}`);
+    }
+
+    return value;
+}
+
+export function envMs(name: string, defaultMs: number, options?: EnvIntOptions): number {
+    return envInt(name, defaultMs, { ...options, min: options?.min ?? 1 });
+}
+
+export function envPort(defaultPort = 3100, options?: EnvIntOptions & { envKey?: string }): number {
+    const envKey = options?.envKey ?? "PORT";
+    return envInt(envKey, defaultPort, { ...options, min: 1, max: 65535 });
+}
+
+export interface EnvNumberOptions {
+    env?: NodeJS.ProcessEnv;
+    min?: number;
+    /** When true, use Math.floor on parsed value. */
+    floor?: boolean;
+}
+
+export function envNumber(name: string, defaultValue: number, options?: EnvNumberOptions): number {
+    const env = options?.env ?? process.env;
+    const raw = readEnv(name, env);
+    if (raw == null) {
+        return defaultValue;
+    }
+
+    const value = Number(raw);
+    if (!Number.isFinite(value)) {
+        throw new Error(`Invalid ${name}: ${raw}`);
+    }
+
+    const min = options?.min;
+    const resolved = options?.floor === true ? Math.floor(value) : value;
+    if (min != null && resolved < min) {
+        throw new Error(`Invalid ${name}: ${raw}`);
+    }
+
+    return resolved;
+}
+
+export function envBool(name: string, defaultValue = false, env: NodeJS.ProcessEnv = process.env): boolean {
+    const raw = readEnv(name, env)?.toLowerCase();
+    if (raw == null) {
+        return defaultValue;
+    }
+    return raw === "1" || raw === "true" || raw === "yes";
+}

package/src/node/env/index.ts

@@ -0,0 +1,10 @@
+export type { EnvIntOptions, EnvNumberOptions } from "./env-parsers";
+export { envBool, envInt, envMs, envNumber, envPort } from "./env-parsers";
+export type { InitSupabaseFromStandardEnvOptions } from "./init-supabase-from-env";
+export { initSupabaseFromStandardEnv } from "./init-supabase-from-env";
+export type { LoadEnvFilesOptions } from "./load-env";
+export { loadEnvFiles, parseEnvFile, parseEnvFileContent, parseEnvLine } from "./load-env";
+export { resolveProjectRootByPackageName, resolveProjectRootFromModule } from "./project-root";
+export type { PublicBaseUrlFromEnvOptions } from "./public-base-url";
+export { publicBaseUrlFromEnv } from "./public-base-url";
+export { readEnv, requireEnv } from "./require-env";

package/src/node/env/init-supabase-from-env.ts

@@ -0,0 +1,38 @@
+import { supabase } from "../../supabase";
+import { loadEnvFiles } from "./load-env";
+import { readEnv, requireEnv } from "./require-env";
+
+export interface InitSupabaseFromStandardEnvOptions {
+    /** Project root for `.env` files (required when `loadEnv` is true). */
+    root?: string;
+    /** Load `.env.local` / `.env` before initialize (default true). */
+    loadEnv?: boolean;
+    /** Hook after env files loaded (legacy aliases, etc.). */
+    afterLoadEnv?: () => void;
+    env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * Load standard Supabase env vars and initialize the process-wide Supabase holder.
+ *
+ * Required: `SUPABASE_URL`, `SUPABASE_ANON_KEY`
+ * Optional: `SUPABASE_NEED_AUTH_URL`, `SUPABASE_NEED_AUTH_ANON_KEY`
+ */
+export async function initSupabaseFromStandardEnv(options: InitSupabaseFromStandardEnvOptions = {}): Promise<void> {
+    const env = options.env ?? process.env;
+    const loadEnv = options.loadEnv ?? true;
+
+    if (loadEnv) {
+        if (options.root == null || options.root === "") {
+            throw new Error("initSupabaseFromStandardEnv: root is required when loadEnv is true");
+        }
+        loadEnvFiles(options.root, { env, afterLoad: options.afterLoadEnv });
+    }
+
+    await supabase.initialize({
+        supabaseUrl: requireEnv("SUPABASE_URL", env),
+        supabaseAnonKey: requireEnv("SUPABASE_ANON_KEY", env),
+        supabaseNeedAuthUrl: readEnv("SUPABASE_NEED_AUTH_URL", env),
+        supabaseNeedAuthAnonKey: readEnv("SUPABASE_NEED_AUTH_ANON_KEY", env),
+    });
+}