target-supabase-sdk 0.1.0

package/src/auth/auth.api.ts

@@ -0,0 +1,85 @@
+import { supabase } from "..";
+import { createResponse } from "../core.interface";
+import { handleSupabaseError } from "../core.utils";
+
+export interface LoginPayload {
+  email: string;
+  password: string;
+}
+
+export interface RegisterPayload {
+  email: string;
+  password: string;
+  confirmPassword?: string;
+}
+
+export interface User {
+  id: string;
+  email: string;
+  created_at: string;
+  last_sign_in_at?: string;
+}
+
+// 用户注册
+export const registerUser = async ({ email, password }: RegisterPayload) => {
+  const { data, error } = await supabase.authClient!.auth.signUp({
+    email,
+    password,
+  });
+
+  if (error) {
+    handleSupabaseError("registerUser", error, "Registration failed. Please try again.");
+  }
+
+  return createResponse.success(data);
+};
+
+// 用户登录
+export const loginUser = async ({ email, password }: LoginPayload) => {
+  const { data, error } = await supabase.authClient!.auth.signInWithPassword({
+    email,
+    password,
+  });
+
+  if (error) {
+    handleSupabaseError("loginUser", error, "Login failed. Please check your credentials.");
+  }
+
+  return createResponse.success(data);
+};
+
+// 用户登出
+export const logoutUser = async () => {
+  const { error } = await supabase.authClient!.auth.signOut();
+
+  if (error) {
+    handleSupabaseError("logoutUser", error, "Logout failed.");
+  }
+
+  return createResponse.success();
+};
+
+// 获取当前用户
+export const getCurrentUser = async () => {
+  const {
+    data: { user },
+    error,
+  } = await supabase.authClient!.auth.getUser();
+
+  if (error) {
+    handleSupabaseError("getCurrentUser", error, "Failed to get current user.");
+  }
+
+  return createResponse.success<User | null>(user as User | null);
+};
+
+// 重置密码
+export const resetPassword = async (email: string) => {
+  const { error } = await supabase.authClient!.auth.resetPasswordForEmail(email);
+
+  if (error) {
+    handleSupabaseError("resetPassword", error, "Password reset request failed.");
+  }
+
+  return createResponse.success();
+};

package/src/core.api.ts

@@ -0,0 +1,338 @@
+import { pick } from "lodash-es";
+import { createResponse, Target } from "./core.interface";
+import { supabase } from ".";
+import { BaseValidator, handleSupabaseError } from "./core.utils";
+import { PostgrestFilterBuilder } from "@supabase/postgrest-js";
+
+export interface QueryFilter {
+  field: string;
+  operator: "eq";
+  value: unknown;
+}
+
+export interface QueryOrderBy {
+  field: string;
+  ascending: boolean;
+}
+
+export interface BaseQueryParams {
+  filterList?: QueryFilter[];
+  orderBy?: QueryOrderBy;
+}
+
+export const getTarget = async ({ id, filterList }: { id: string; filterList?: QueryFilter[] }) => {
+  const query =
+    filterList != null && filterList.length > 0
+      ? filterList.reduce((query, filter) => {
+          switch (filter.operator) {
+            case "eq":
+              return query.eq(filter.field, filter.value);
+            default:
+              return query;
+          }
+        }, supabase.client.from("target").select().eq("id", id))
+      : supabase.client.from("target").select().eq("id", id);
+
+  const { data, error } = await query.single();
+  if (error) {
+    handleSupabaseError("getTarget", error, "Failed to fetch target.");
+  }
+  return createResponse.success<Target>(data as Target);
+};
+
+export const getPossibleTarget = async ({ filterList }: { filterList: QueryFilter[] }) => {
+  const query = filterList.reduce((query, filter) => {
+    switch (filter.operator) {
+      case "eq":
+        return query.eq(filter.field, filter.value);
+      default:
+        return query;
+    }
+  }, supabase.client.from("target").select());
+
+  const { data, error } = await query.maybeSingle();
+  if (error) {
+    handleSupabaseError("getPossibleTarget", error, "Failed to fetch target.");
+  }
+  return createResponse.success<Target | null>(data);
+};
+
+export interface GetTargetListParams extends BaseQueryParams {
+  pageNum: number;
+  pageSize: number;
+  category: Target["category"];
+}
+
+export const getTargetList = async ({
+  pageNum,
+  pageSize,
+  category,
+  filterList = [],
+  orderBy = { field: "created_at", ascending: false },
+  filterBuilder,
+}: GetTargetListParams & {
+  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+  filterBuilder?: PostgrestFilterBuilder<any, any, any[], "target", unknown>;
+}) => {
+  const query =
+    filterBuilder ??
+    filterList.reduce((query, filter) => {
+      switch (filter.operator) {
+        case "eq":
+          return query.eq(filter.field, filter.value);
+        default:
+          return query;
+      }
+    }, supabase.client.from("target").select("*").eq("category", category));
+
+  const { data, error } = await query
+    .order(orderBy.field, { ascending: orderBy.ascending })
+    .range(pageNum * pageSize, (pageNum + 1) * pageSize - 1);
+
+  if (error) {
+    handleSupabaseError("getTargetList", error, "Failed to fetch target list.");
+  }
+  return createResponse.success<Target[]>(data);
+};
+
+export interface GetTargetTotalCountParams extends BaseQueryParams {
+  category: Target["category"];
+  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+  filterBuilder?: PostgrestFilterBuilder<any, any, any[], "target", unknown>;
+}
+
+export const getTargetTotalCount = async ({
+  category,
+  filterList = [],
+  filterBuilder,
+}: GetTargetTotalCountParams) => {
+  const query =
+    filterBuilder ??
+    filterList.reduce(
+      (query, filter) => {
+        switch (filter.operator) {
+          case "eq":
+            return query.eq(filter.field, filter.value);
+          default:
+            return query;
+        }
+      },
+      supabase.client
+        .from("target")
+        .select("id", { count: "exact", head: true }) // head: true means no row payload
+        .eq("category", category)
+    );
+
+  const { count, error } = await query;
+
+  if (error) {
+    handleSupabaseError("getTargetTotalCount", error, "Failed to fetch target count.");
+  }
+  return createResponse.success<number>(count ?? 0);
+};
+
+export const deleteTarget = async ({ id, filterList }: { id: string; filterList?: QueryFilter[] }) => {
+  // Check whether the target exists given filterList
+  if (filterList != null && filterList.length > 0) {
+    const query = filterList.reduce((query, filter) => {
+      switch (filter.operator) {
+        case "eq":
+          return query.eq(filter.field, filter.value);
+        default:
+          return query;
+      }
+    }, supabase.client.from("target").select().eq("id", id));
+    const { data: existingTarget, error: existingError } = await query.single();
+    if (existingError || existingTarget == null) {
+      const msg = `[deleteTarget] Cannot find the target ${id}`;
+      console.error(msg, { filterList }, existingError);
+      throw new Error(msg);
+    }
+  }
+  const { error } = await supabase.client.from("target").delete().eq("id", id);
+  if (error) {
+    handleSupabaseError("deleteTarget", error, `Failed to delete target ${id}.`);
+  }
+  return createResponse.success();
+};
+
+export interface PostTargetPayload {
+  name: Target["name"];
+  category: Target["category"];
+  value: Target["value"];
+  tagList: Target["tagList"];
+  extra?: Target["extra"];
+  details?: Target["details"];
+}
+
+class PostTargetPayloadValidator extends BaseValidator<PostTargetPayload> {
+  protected requiredFields: (keyof PostTargetPayload)[] = ["category", "name", "value", "tagList"];
+  protected optionalFields: (keyof PostTargetPayload)[] = ["extra", "details"];
+
+  constructor() {
+    super();
+    // Add custom
+    this.addValidator((val) => {
+      return true;
+    });
+  }
+}
+
+export const postTarget = async (payload: PostTargetPayload) => {
+  const validPayload = new PostTargetPayloadValidator().validate(payload);
+
+  const { data, error } = await supabase.client
+    .from("target")
+    .insert([{ ...validPayload }])
+    .select()
+    .single();
+
+  if (error) {
+    handleSupabaseError("postTarget", error, "Failed to create target.");
+  }
+  return createResponse.success<Target>(data as Target);
+};
+
+export interface PatchTargetPayload extends PostTargetPayload {
+  id: string;
+}
+
+export const patchTarget = async ({ id, ...restPayload }: PatchTargetPayload) => {
+  const { data: currentData, error: fetchError } = await supabase.client.from("target").select().eq("id", id).single();
+  if (!currentData) {
+    throw new Error("Target NOT exists");
+  }
+  if (fetchError) handleSupabaseError("patchTarget", fetchError, "Failed to fetch target.");
+
+  const updatedTarget = new PostTargetPayloadValidator().validate(restPayload);
+
+  const { data, error } = await supabase.client
+    .from("target")
+    .update({
+      ...updatedTarget,
+    })
+    .eq("id", id)
+    .select()
+    .single();
+
+  if (error) {
+    handleSupabaseError("patchTarget", error, "Failed to update target.");
+  }
+  return createResponse.success<Target>(data as Target);
+};
+
+export const updateTargetDetails = async <T, D>({
+  id,
+  updateFn,
+  beforeUpdateValidator = () => true,
+  updateExtraFn,
+}: {
+  id: string;
+  updateFn: (existing: D) => D;
+  beforeUpdateValidator?: (existing: D) => true | string;
+  updateExtraFn?: (existing: D) => string;
+}) => {
+  const { data: currentData, error: fetchError } = await supabase.client
+    .from("target")
+    .select("details")
+    .eq("id", id)
+    .single();
+  if (!currentData) {
+    const msg = "[updateTargetDetails] Target NOT exists: " + id;
+    console.error(msg);
+    throw new Error(msg);
+  }
+
+  const currentDetails = currentData.details as D;
+
+  // Check before update
+  const validatorResult = beforeUpdateValidator(currentDetails);
+  if (validatorResult !== true) {
+    throw new Error("[updateTargetDetails] validation failed. " + validatorResult);
+  }
+
+  const updatedDetails: D = updateFn(currentDetails);
+  const updated =
+    updateExtraFn == null
+      ? {
+          details: updatedDetails,
+        }
+      : {
+          details: updatedDetails,
+          extra: updateExtraFn(currentDetails),
+        };
+
+  const { data, error } = await supabase.client.from("target").update(updated).eq("id", id).select().single();
+
+  if (error) handleSupabaseError("updateTargetDetails", error, "Failed to update target details.");
+  return data as T;
+};
+
+export const createTarget = async <T extends Target, P extends object>({
+  payload,
+  validator,
+  createFn,
+  checkRedundancyFilterList,
+  upsert = false,
+}: {
+  payload: P;
+  validator?: new () => BaseValidator<P>;
+  createFn: (validPayload: P) => Omit<T, "id" | "created_at">;
+  checkRedundancyFilterList?: QueryFilter[];
+  upsert?: boolean;
+}) => {
+  // (Optional)Step 1: validate payload
+  const validPayload = validator != null ? new validator().validate(payload) : payload;
+
+  // (Optional)Step 2: check redundancy
+  if (checkRedundancyFilterList != null && checkRedundancyFilterList.length > 0) {
+    const query = checkRedundancyFilterList.reduce((query, filter) => {
+      switch (filter.operator) {
+        case "eq":
+          return query.eq(filter.field, filter.value);
+        default:
+          return query;
+      }
+    }, supabase.client.from("target").select("id"));
+    const { data: existingTarget, error: existingError } = await query.maybeSingle();
+    if (existingError) {
+      handleSupabaseError("createTarget", existingError, "Failed to check target existence.");
+    }
+    if (existingTarget) {
+      if (upsert) {
+        const newTarget = createFn(validPayload);
+        const updated = pick(newTarget, ["category", "name", "value", "tagList", "extra", "details"]);
+        const { data, error } = await supabase.client
+          .from("target")
+          .update(updated)
+          .eq("id", existingTarget.id)
+          .select()
+          .single();
+        if (error) {
+          handleSupabaseError("createTarget", error, "Failed to update existing target.");
+        }
+        return createResponse.success<T>(data);
+      }
+      const msg = "[createTarget] Target already exists";
+      console.error(msg, checkRedundancyFilterList);
+      throw new Error(msg);
+    }
+  }
+
+  // Step 3: create target
+  const newTarget = createFn(validPayload);
+  const { data, error } = await supabase.client.from("target").insert([newTarget]).select().single();
+  if (error) {
+    handleSupabaseError("createTarget", error, "Failed to create target.");
+  }
+  return createResponse.success<T>(data);
+};
+
+export function validateWith<P extends object, V extends BaseValidator<P>>(ValidatorClass: new () => V) {
+  return <R>(fn: (validPayload: P) => R) => {
+    return (payload: P): R => {
+      const validPayload = new ValidatorClass().validate(payload);
+      return fn(validPayload);
+    };
+  };
+}

package/src/core.interface.ts

@@ -0,0 +1,74 @@
+import { 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;
+}
+
+export enum StatusCode {
+  SUCCESS = 200,
+  ERROR = 400,
+}
+
+export interface SupabaseResponse<T = unknown> {
+  status_code: StatusCode;
+  success: boolean;
+  message?: string;
+  data?: T;
+  error?: {
+    message: string;
+    code?: string;
+  };
+}
+
+export const createResponse = {
+  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,
+      },
+    };
+  },
+};

package/src/core.utils.ts

@@ -0,0 +1,98 @@
+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;
+}
+
+export function logDev(...args: unknown[]): void {
+  if (isDevEnvironment()) {
+    console.log(...args);
+  }
+}
+
+export function logDevGroup(label: string, fn: () => void): void {
+  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`);
+}
+
+/** 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)[] = [];
+
+  /** @deprecated -> addCustomValidator */
+  addValidator(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;
+  }
+
+  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 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");
+
+      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
+
+    return { ...required, ...optional } as T;
+  };
+}

package/src/feed/feed.interface.ts

@@ -0,0 +1,33 @@
+import { Target } from "../core.interface";
+
+export interface Feed extends Target {
+  category: CategoryFeed;
+  details: FeedDetails;
+}
+
+export enum CategoryFeed {
+  FEED = "feed",
+  DOC = "doc",
+}
+
+export interface FeedDetails {
+  manifestVersion: number;
+  list: FeedItem[];
+}
+
+export enum FeedItemType {
+  /** Plain Target */
+  TEXT = "TEXT",
+  /** Parcel */
+  IMAGE = "IMAGE",
+  /** Parcel */
+  VIDEO = "VIDEO",
+  /** TODO Review */
+  // REVIEW = "REVIEW",
+}
+
+export interface FeedItem {
+  index: number;
+  type: FeedItemType;
+  refTargetId: string;
+}