target-supabase-sdk 0.1.7 → 0.1.8

package/src/auth/auth.api.ts

@@ -1,5 +1,5 @@
 import { supabase } from "..";
-import { createResponse } from "../core.interface";
+import { generateResponse } from "../core.interface";
 import { handleSupabaseError } from "../core.utils";
 
 export interface LoginPayload {
@@ -31,7 +31,7 @@ export const registerUser = async ({ email, password }: RegisterPayload) => {
     handleSupabaseError("registerUser", error, "Registration failed. Please try again.");
   }
 
-  return createResponse.success(data);
+  return generateResponse.success(data);
 };
 
 // 用户登录
@@ -45,7 +45,7 @@ export const loginUser = async ({ email, password }: LoginPayload) => {
     handleSupabaseError("loginUser", error, "Login failed. Please check your credentials.");
   }
 
-  return createResponse.success(data);
+  return generateResponse.success(data);
 };
 
 // 用户登出
@@ -56,7 +56,7 @@ export const logoutUser = async () => {
     handleSupabaseError("logoutUser", error, "Logout failed.");
   }
 
-  return createResponse.success();
+  return generateResponse.success();
 };
 
 // 获取当前用户
@@ -70,7 +70,7 @@ export const getCurrentUser = async () => {
     handleSupabaseError("getCurrentUser", error, "Failed to get current user.");
   }
 
-  return createResponse.success<User | null>(user as User | null);
+  return generateResponse.success<User | null>(user as User | null);
 };
 
 // 重置密码
@@ -81,5 +81,5 @@ export const resetPassword = async (email: string) => {
     handleSupabaseError("resetPassword", error, "Password reset request failed.");
   }
 
-  return createResponse.success();
+  return generateResponse.success();
 };

package/src/core.api.ts

@@ -1,15 +1,39 @@
-import { pick } from "lodash-es";
-import { createResponse, Target } from "./core.interface";
+import { generateResponse, Target, TargetPayload } 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";
+  operator: "eq" | "neq" | "in";
   value: unknown;
 }
 
+// biome-ignore lint/suspicious/noExplicitAny: PostgrestFilterBuilder is generic over schema
+function applyQueryFilter<Q extends PostgrestFilterBuilder<any, any, any, any, any>>(
+  query: Q,
+  filter: QueryFilter
+): Q {
+  switch (filter.operator) {
+    case "eq":
+      return query.eq(filter.field, filter.value) as Q;
+    case "neq":
+      return query.neq(filter.field, filter.value) as Q;
+    case "in":
+      return query.in(filter.field, filter.value as unknown[]) as Q;
+    default:
+      return query;
+  }
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: PostgrestFilterBuilder is generic over schema
+function applyQueryFilters<Q extends PostgrestFilterBuilder<any, any, any, any, any>>(
+  query: Q,
+  filterList: QueryFilter[]
+): Q {
+  return filterList.reduce((q, filter) => applyQueryFilter(q, filter), query);
+}
+
 export interface QueryOrderBy {
   field: string;
   ascending: boolean;
@@ -23,38 +47,24 @@ export interface BaseQueryParams {
 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))
+      ? applyQueryFilters(supabase.client.from("target").select().eq("id", id), filterList)
       : 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);
+  return generateResponse.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 query = applyQueryFilters(supabase.client.from("target").select(), filterList);
 
   const { data, error } = await query.maybeSingle();
   if (error) {
     handleSupabaseError("getPossibleTarget", error, "Failed to fetch target.");
   }
-  return createResponse.success<Target | null>(data);
+  return generateResponse.success<Target | null>(data);
 };
 
 export interface GetTargetListParams extends BaseQueryParams {
@@ -71,19 +81,12 @@ export const getTargetList = async ({
   orderBy = { field: "created_at", ascending: false },
   filterBuilder,
 }: GetTargetListParams & {
-  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+  // biome-ignore lint/suspicious/noExplicitAny: PostgrestFilterBuilder is generic over schema
   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));
+    applyQueryFilters(supabase.client.from("target").select("*").eq("category", category), filterList);
 
   const { data, error } = await query
     .order(orderBy.field, { ascending: orderBy.ascending })
@@ -92,15 +95,14 @@ export const getTargetList = async ({
   if (error) {
     handleSupabaseError("getTargetList", error, "Failed to fetch target list.");
   }
-  return createResponse.success<Target[]>(data);
+  return generateResponse.success<Target[]>(data);
 };
 
 export interface GetTargetTotalCountParams extends BaseQueryParams {
   category: Target["category"];
-  // biome-ignore lint/suspicious/noExplicitAny: <explanation>
+  // biome-ignore lint/suspicious/noExplicitAny: PostgrestFilterBuilder is generic over schema
   filterBuilder?: PostgrestFilterBuilder<any, any, any[], "target", unknown>;
 }
-
 export const getTargetTotalCount = async ({
   category,
   filterList = [],
@@ -108,19 +110,12 @@ export const getTargetTotalCount = async ({
 }: GetTargetTotalCountParams) => {
   const query =
     filterBuilder ??
-    filterList.reduce(
-      (query, filter) => {
-        switch (filter.operator) {
-          case "eq":
-            return query.eq(filter.field, filter.value);
-          default:
-            return query;
-        }
-      },
+    applyQueryFilters(
       supabase.client
         .from("target")
-        .select("id", { count: "exact", head: true }) // head: true means no row payload
-        .eq("category", category)
+        .select("id", { count: "exact", head: true })
+        .eq("category", category),
+      filterList
     );
 
   const { count, error } = await query;
@@ -128,20 +123,13 @@ export const getTargetTotalCount = async ({
   if (error) {
     handleSupabaseError("getTargetTotalCount", error, "Failed to fetch target count.");
   }
-  return createResponse.success<number>(count ?? 0);
+  return generateResponse.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 query = applyQueryFilters(supabase.client.from("target").select().eq("id", id), filterList);
     const { data: existingTarget, error: existingError } = await query.single();
     if (existingError || existingTarget == null) {
       const msg = `[deleteTarget] Cannot find the target ${id}`;
@@ -153,7 +141,7 @@ export const deleteTarget = async ({ id, filterList }: { id: string; filterList?
   if (error) {
     handleSupabaseError("deleteTarget", error, `Failed to delete target ${id}.`);
   }
-  return createResponse.success();
+  return generateResponse.success();
 };
 
 export interface PostTargetPayload {
@@ -172,7 +160,7 @@ class PostTargetPayloadValidator extends BaseValidator<PostTargetPayload> {
   constructor() {
     super();
     // Add custom
-    this.addValidator((val) => {
+    this.addCustomValidator((val) => {
       return true;
     });
   }
@@ -190,7 +178,7 @@ export const postTarget = async (payload: PostTargetPayload) => {
   if (error) {
     handleSupabaseError("postTarget", error, "Failed to create target.");
   }
-  return createResponse.success<Target>(data as Target);
+  return generateResponse.success<Target>(data as Target);
 };
 
 export interface PatchTargetPayload extends PostTargetPayload {
@@ -218,25 +206,55 @@ export const patchTarget = async ({ id, ...restPayload }: PatchTargetPayload) =>
   if (error) {
     handleSupabaseError("patchTarget", error, "Failed to update target.");
   }
-  return createResponse.success<Target>(data as Target);
+  return generateResponse.success<Target>(data as Target);
 };
 
+/**
+ * Read-modify-write `target.details` with optional DB-level optimistic locking on UPDATE.
+ *
+ * Do not use application-layer pre-update validators (e.g. checking state after SELECT then
+ * UPDATE with only `id`). That pattern is not atomic and loses under concurrency. Pass expected
+ * row conditions via `optimisticLockFilterList` so they are applied on the UPDATE statement.
+ */
+export interface UpdateTargetDetailsParams<D> {
+  /** Target row id. */
+  id: string;
+  /**
+   * Computes new details from the row fetched immediately before UPDATE.
+   * Runs after SELECT; the write still relies on `optimisticLockFilterList` for atomic guards.
+   */
+  updateFn: (existing: D) => D;
+  /**
+   * Optional `target.extra` derived from existing details (written together with details).
+   */
+  updateExtraFn?: (existing: D) => string;
+  /**
+   * Optimistic lock conditions applied on UPDATE (not on the prior SELECT).
+   *
+   * Replaces the removed `beforeUpdateValidator`: validators ran in app code between read and
+   * write and could not prevent concurrent overwrites. These filters become part of the UPDATE
+   * WHERE clause (via `applyQueryFilters`), e.g. `{ field: "details->>status", operator: "eq", value: "TODO" }`.
+   *
+   * If no row matches after UPDATE, throws "Optimistic lock failed". Empty array = update by id only.
+   */
+  optimisticLockFilterList?: QueryFilter[];
+}
+
 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;
-}) => {
+  optimisticLockFilterList = [],
+}: UpdateTargetDetailsParams<D>) => {
   const { data: currentData, error: fetchError } = await supabase.client
     .from("target")
     .select("details")
     .eq("id", id)
     .single();
+
+  if (fetchError) {
+    handleSupabaseError("updateTargetDetails", fetchError, "Failed to fetch target.");
+  }
   if (!currentData) {
     const msg = "[updateTargetDetails] Target NOT exists: " + id;
     console.error(msg);
@@ -244,30 +262,85 @@ export const updateTargetDetails = async <T, D>({
   }
 
   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,
+      }
       : {
-          details: updatedDetails,
-          extra: updateExtraFn(currentDetails),
-        };
+        details: updatedDetails,
+        extra: updateExtraFn(currentDetails),
+      };
+
+  const updateQuery = applyQueryFilters(
+    supabase.client.from("target").update(updated).eq("id", id),
+    optimisticLockFilterList
+  );
 
-  const { data, error } = await supabase.client.from("target").update(updated).eq("id", id).select().single();
+  const { data, error } = await updateQuery.select().maybeSingle();
+
+  if (error) {
+    handleSupabaseError("updateTargetDetails", error, "Failed to update target details.");
+  }
+  if (!data) {
+    const msg =
+      optimisticLockFilterList.length > 0
+        ? OPTIMISTIC_LOCK_FAILED_MESSAGE
+        : "[updateTargetDetails] Target not found or was deleted.";
+    throw new Error(msg);
+  }
 
-  if (error) handleSupabaseError("updateTargetDetails", error, "Failed to update target details.");
   return data as T;
 };
 
+export const OPTIMISTIC_LOCK_FAILED_MESSAGE =
+  "[updateTargetDetails] Optimistic lock failed: target no longer matches expected state.";
+
+export const CREATE_TARGET_ALREADY_EXISTS_MESSAGE = "[createTarget] Target already exists";
+
+const CREATE_TARGET_REDUNDANCY_MISMATCH_MESSAGE =
+  "[createTarget] Inserted row does not match checkRedundancyFilterList; verify createFn aligns with filters.";
+
+/** Max rows to fetch during post-verify — only need to detect one other match. */
+const REDUNDANCY_VERIFY_ROW_LIMIT = 2;
+
+export function isOptimisticLockError(error: unknown): boolean {
+  return error instanceof Error && error.message === OPTIMISTIC_LOCK_FAILED_MESSAGE;
+}
+
+export function isCreateTargetAlreadyExistsError(error: unknown): boolean {
+  return error instanceof Error && error.message === CREATE_TARGET_ALREADY_EXISTS_MESSAGE;
+}
+
+/** Roll back an optimistic insert when redundancy filters match other rows. */
+async function rollbackCreateTargetInsert(id: string) {
+  const { error } = await supabase.client.from("target").delete().eq("id", id);
+  if (error) {
+    handleSupabaseError("createTarget", error, "Failed to rollback conflicting insert.");
+  }
+}
+
+/** Roll back the new row and signal a redundancy conflict to the caller. */
+function throwCreateTargetAlreadyExists(checkRedundancyFilterList: QueryFilter[]): never {
+  console.error(CREATE_TARGET_ALREADY_EXISTS_MESSAGE, checkRedundancyFilterList);
+  throw new Error(CREATE_TARGET_ALREADY_EXISTS_MESSAGE);
+}
+
+async function failCreateTargetRedundancy(
+  selfId: string,
+  checkRedundancyFilterList: QueryFilter[]
+): Promise<never> {
+  await rollbackCreateTargetInsert(selfId);
+  return throwCreateTargetAlreadyExists(checkRedundancyFilterList);
+}
+
+/**
+ * Create a `target` row with optional payload validation and optimistic redundancy checks.
+ *
+ * When `checkRedundancyFilterList` is set, uses insert-first + post-verify (not SELECT-before-INSERT).
+ * See `.cursor/skills/create-target-redundancy/SKILL.md`.
+ */
 export const createTarget = async <T extends Target, P extends object>({
   payload,
   validator,
@@ -277,55 +350,59 @@ export const createTarget = async <T extends Target, P extends object>({
 }: {
   payload: P;
   validator?: new () => BaseValidator<P>;
-  createFn: (validPayload: P) => Omit<T, "id" | "created_at">;
+  createFn: (validPayload: P) => TargetPayload<T>;
+  /** Business-key filters; if another row matches after insert, conflict handling runs. */
   checkRedundancyFilterList?: QueryFilter[];
+  /**
+   * @deprecated Not supported — ignored at runtime. Use domain patch APIs or future RPC upsert.
+   * Reserved for a later release; do not pass `true`.
+   */
   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);
-    }
+  if (upsert) {
+    console.warn("[createTarget] `upsert` is deprecated and has no effect.");
   }
 
-  // Step 3: create target
+  const validPayload = validator != null ? new validator().validate(payload) : payload;
   const newTarget = createFn(validPayload);
+
+  const hasRedundancyCheck =
+    checkRedundancyFilterList != null && checkRedundancyFilterList.length > 0;
+
+  // 1. Optimistic insert (see create-target-redundancy skill)
   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);
+
+  if (!hasRedundancyCheck) {
+    return generateResponse.success<T>(data);
+  }
+
+  // 2. Post-verify: limit(2) — enough to detect one other row matching the business-key filters
+  const { data: matches, error: matchError } = await applyQueryFilters(
+    supabase.client.from("target").select("id"),
+    checkRedundancyFilterList
+  ).limit(REDUNDANCY_VERIFY_ROW_LIMIT);
+  if (matchError) {
+    handleSupabaseError("createTarget", matchError, "Failed to verify target redundancy.");
+  }
+
+  const selfId = data.id as string;
+  const rows = matches ?? [];
+  const selfMatchesFilters = rows.some((row) => row.id === selfId);
+  if (!selfMatchesFilters) {
+    console.warn(CREATE_TARGET_REDUNDANCY_MISMATCH_MESSAGE, checkRedundancyFilterList);
+  }
+
+  const hasOtherRow = rows.some((row) => row.id !== selfId);
+
+  // 3. No conflict — keep the inserted row; otherwise rollback and reject
+  if (!hasOtherRow) {
+    return generateResponse.success<T>(data);
+  }
+
+  return failCreateTargetRedundancy(selfId, checkRedundancyFilterList);
 };
 
 export function validateWith<P extends object, V extends BaseValidator<P>>(ValidatorClass: new () => V) {

package/src/core.interface.ts

@@ -11,6 +11,8 @@ export interface Target {
   created_at: string;
 }
 
+export type TargetPayload<T extends Target> = Omit<T, "id" | "created_at">;
+
 export enum StatusCode {
   SUCCESS = 200,
   ERROR = 400,
@@ -27,7 +29,7 @@ export interface SupabaseResponse<T = unknown> {
   };
 }
 
-export const createResponse = {
+export const generateResponse = {
   success<T>(data?: T, message?: string): SupabaseResponse<T> {
     return {
       status_code: StatusCode.SUCCESS,

package/src/core.utils.ts

@@ -42,12 +42,6 @@ export abstract class BaseValidator<T extends object> {
   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;

package/src/file-list/file-list.api.ts

@@ -9,7 +9,7 @@ export class PostCreateFileListValidator extends BaseValidator<PostCreateFileLis
   constructor() {
     super();
     // Add custom
-    this.addValidator((val) => {
+    this.addCustomValidator((val) => {
       return true;
     });
   }

package/src/index.ts

@@ -56,3 +56,9 @@ export * from "./link/link.api";
 
 export * from "./list/list.interface";
 export * from "./list/list.api";
+
+export * from "./word/word.interface";
+
+export * from "./task/task.interface";
+
+export * from "./repo/repo.interface";

package/src/list/list.interface.ts

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