target-supabase-sdk 0.1.9 → 0.2.1

package/src/service/service.api.ts

@@ -0,0 +1,294 @@
+import { z } from "zod";
+import { createTarget, getPossibleTarget, getTarget, type QueryFilter, validateWithSchema } from "../core.api";
+import { type FieldDefinition, type SchemaDefinition, ServiceLifecycleStatus } from "./base.interface";
+import {
+    type Api,
+    type ApiDetails,
+    ApiMethod,
+    CategoryApi,
+    CategoryService,
+    type Service,
+    type ServiceDetails,
+} from "./service.interface";
+
+const targetIdSchema = z.string().trim().min(1);
+
+const enumMemberSchema = z.object({
+    key: z.string().trim().min(1),
+    value: z.string(),
+});
+
+const fieldPresenceSchema = z.object({
+    nullable: z.boolean(),
+    optional: z.boolean(),
+});
+
+const schemaDefinitionSchema: z.ZodType<SchemaDefinition> = z.lazy(() =>
+    z.discriminatedUnion("type", [
+        fieldPresenceSchema.extend({
+            type: z.literal("string"),
+            min: z.number().optional(),
+            max: z.number().optional(),
+            regex: z.string().optional(),
+            default: z.string().optional(),
+        }),
+        fieldPresenceSchema.extend({
+            type: z.literal("number"),
+            min: z.number().optional(),
+            max: z.number().optional(),
+            default: z.number().optional(),
+        }),
+        fieldPresenceSchema.extend({
+            type: z.literal("boolean"),
+            default: z.boolean().optional(),
+        }),
+        fieldPresenceSchema.extend({
+            type: z.literal("unknown"),
+            default: z.unknown().optional(),
+        }),
+        fieldPresenceSchema.extend({
+            type: z.literal("enum"),
+            members: z.array(enumMemberSchema).min(1),
+            defaultKey: z.string().trim().min(1).optional(),
+        }),
+        fieldPresenceSchema.extend({
+            type: z.literal("object"),
+            fields: z.array(fieldDefinitionSchema),
+            default: z.record(z.unknown()).optional(),
+        }),
+        fieldPresenceSchema.extend({
+            type: z.literal("array"),
+            items: schemaDefinitionSchema,
+            min: z.number().int().nonnegative().optional(),
+            max: z.number().int().nonnegative().optional(),
+            default: z.unknown().optional(),
+        }),
+    ]),
+);
+
+const fieldDefinitionSchema: z.ZodType<FieldDefinition> = z.intersection(
+    z.object({ fieldName: z.string().trim().min(1) }),
+    schemaDefinitionSchema,
+);
+
+export { fieldDefinitionSchema, schemaDefinitionSchema };
+
+export const serviceLifecycleSchema = z.object({
+    status: z.nativeEnum(ServiceLifecycleStatus),
+    activeSince: z.string().trim().min(1),
+    deprecatedAt: z.string().nullable(),
+    sunsetAt: z.string().nullable(),
+});
+
+export const apiDetailsSchema = z.object({
+    method: z.nativeEnum(ApiMethod),
+    path: z.string().trim().min(1),
+    endpoint: z.string().trim().min(1),
+    request: z.object({
+        query: z.array(fieldDefinitionSchema),
+    }),
+    response: z.object({
+        "200": z.array(fieldDefinitionSchema),
+    }),
+    manifestVersion: z.number().int().nonnegative(),
+    lifecycle: serviceLifecycleSchema,
+});
+
+export const serviceDetailsSchema = z.object({
+    manifestVersion: z.number().int().nonnegative(),
+    apiKeys: z.array(z.string().trim().min(1)),
+    dependencies: z.array(z.string().trim().min(1)).default([]),
+    lifecycle: serviceLifecycleSchema,
+});
+
+export const postApiSchema = z.object({
+    name: z.string().trim().min(1),
+    value: z.string().trim().min(1),
+    details: apiDetailsSchema,
+    tagList: z.array(z.string()).optional().default([]),
+    extra: z.string().optional(),
+});
+
+export type PostApiPayload = z.infer<typeof postApiSchema>;
+
+export const getApiSchema = z
+    .object({
+        id: targetIdSchema.optional(),
+        value: z.string().trim().min(1).optional(),
+    })
+    .refine(
+        (payload) => {
+            const hasId = payload.id != null && payload.id !== "";
+            const hasValue = payload.value != null && payload.value !== "";
+            return hasId !== hasValue;
+        },
+        { message: "Provide exactly one of id or value" },
+    );
+
+export type GetApiPayload = z.infer<typeof getApiSchema>;
+
+export const getServiceSchema = z
+    .object({
+        id: targetIdSchema.optional(),
+        value: z.string().trim().min(1).optional(),
+        /** When set, filters `details.lifecycle.status` at query time. */
+        lifecycleStatus: z.nativeEnum(ServiceLifecycleStatus).optional(),
+    })
+    .refine(
+        (payload) => {
+            const hasId = payload.id != null && payload.id !== "";
+            const hasValue = payload.value != null && payload.value !== "";
+            return hasId !== hasValue;
+        },
+        { message: "Provide exactly one of id or value" },
+    );
+
+export type GetServicePayload = z.infer<typeof getServiceSchema>;
+
+export const postServiceSchema = z.object({
+    name: z.string().trim().min(1),
+    value: z.string().trim().min(1),
+    details: serviceDetailsSchema,
+    tagList: z.array(z.string()).optional().default([]),
+    extra: z.string().optional(),
+});
+
+export type PostServicePayload = z.infer<typeof postServiceSchema>;
+
+const apiCategoryFilter = {
+    field: "category",
+    operator: "eq" as const,
+    value: CategoryApi.API,
+};
+
+const serviceCategoryFilter = {
+    field: "category",
+    operator: "eq" as const,
+    value: CategoryService.SERVICE,
+};
+
+const SERVICE_LIFECYCLE_STATUS_FIELD = "details->lifecycle->>status" as const;
+
+function buildServiceLookupFilters(payload: GetServicePayload): QueryFilter[] {
+    const filters: QueryFilter[] = [serviceCategoryFilter];
+
+    if (payload.id != null && payload.id !== "") {
+        // id path: caller adds .eq("id", id) separately
+    } else {
+        filters.push({ field: "value", operator: "eq", value: payload.value! });
+    }
+
+    if (payload.lifecycleStatus != null) {
+        filters.push({
+            field: SERVICE_LIFECYCLE_STATUS_FIELD,
+            operator: "eq",
+            value: payload.lifecycleStatus,
+        });
+    }
+
+    return filters;
+}
+
+/** Register an Api contract row (`category=api`). */
+export const postApi = validateWithSchema(
+    postApiSchema,
+    "postApiSchema",
+)(async ({ name, value, details, tagList, extra }) => {
+    return createTarget<Api, PostApiPayload>({
+        payload: { name, value, details, tagList, extra },
+        createFn: () => ({
+            name,
+            value,
+            category: CategoryApi.API,
+            tagList,
+            extra,
+            details: details as ApiDetails,
+        }),
+    });
+});
+
+/** Fetch an Api by id or by {@link Api.value} key (`category=api`). */
+export const getApi = validateWithSchema(
+    getApiSchema,
+    "getApiSchema",
+)(async (payload) => {
+    if (payload.id != null && payload.id !== "") {
+        const result = await getTarget({
+            id: payload.id,
+            filterList: [apiCategoryFilter],
+        });
+        return {
+            ...result,
+            data: result.data as Api,
+        };
+    }
+
+    const result = await getPossibleTarget({
+        filterList: [apiCategoryFilter, { field: "value", operator: "eq", value: payload.value! }],
+    });
+
+    if (result.data == null) {
+        return {
+            ...result,
+            data: undefined,
+        };
+    }
+
+    return {
+        ...result,
+        data: result.data as Api,
+    };
+});
+
+/** Fetch a Service by id or by {@link Service.value} key (`category=service`). */
+export const getService = validateWithSchema(
+    getServiceSchema,
+    "getServiceSchema",
+)(async (payload) => {
+    const filterList = buildServiceLookupFilters(payload);
+
+    if (payload.id != null && payload.id !== "") {
+        const result = await getTarget({
+            id: payload.id,
+            filterList,
+        });
+        return {
+            ...result,
+            data: result.data as Service,
+        };
+    }
+
+    const result = await getPossibleTarget({
+        filterList,
+    });
+
+    if (result.data == null) {
+        return {
+            ...result,
+            data: undefined,
+        };
+    }
+
+    return {
+        ...result,
+        data: result.data as Service,
+    };
+});
+
+/** Register a Service catalog row (`category=service`). */
+export const postService = validateWithSchema(
+    postServiceSchema,
+    "postServiceSchema",
+)(async ({ name, value, details, tagList, extra }) => {
+    return createTarget<Service, PostServicePayload>({
+        payload: { name, value, details, tagList, extra },
+        createFn: () => ({
+            name,
+            value,
+            category: CategoryService.SERVICE,
+            tagList,
+            extra,
+            details: details as ServiceDetails,
+        }),
+    });
+});

package/src/service/service.interface.ts

@@ -1,27 +1,59 @@
-import { Target } from "../core.interface";
-import { Lifecycle } from "./base.interface";
+import type { Target } from "../core.interface";
+import type { FieldDefinition, ServiceLifecycle } from "./base.interface";
 
 export interface Service extends Target {
-  /** "storage-service" 唯一键 */
-  value: string;
-  category: CategoryService;
-  details: ServiceDetails;
+    name: string;
+    /** "storage-service" 唯一键 */
+    value: string;
+    category: CategoryService;
+    details: ServiceDetails;
 }
 
 export enum CategoryService {
-  SERVICE = "service",
+    SERVICE = "service",
 }
 
-export enum ServiceStatus {
-  ACTIVE = "ACTIVE",
-  DEPRECATED = "DEPRECATED",
-  SUNSET = "SUNSET",
+export interface ServiceDetails {
+    manifestVersion: number;
+    /** 能力 Api keys */
+    apiKeys: string[];
+    /** 依赖的服务 Service keys */
+    dependencies: string[];
+    lifecycle: ServiceLifecycle;
 }
 
-export interface ServiceDetails {
-  /** 能力 Api keys */
-  apis: string[];
-  /** 依赖的服务 Service keys */
-  dependencies: string[];
-  lifecycle: Lifecycle;
+export interface Api extends Target {
+    /** "core.post.target.0" 唯一键 领域 + METHOD + content + VERSION */
+    value: string;
+    category: CategoryApi;
+    details: ApiDetails;
+}
+
+export enum CategoryApi {
+    API = "api",
+}
+
+export enum ApiMethod {
+    POST = "POST",
+    GET = "GET",
+    PUT = "PUT",
+    DELETE = "DELETE",
+}
+
+export interface ApiDetails {
+    method: ApiMethod;
+    /** /v0/core/target */
+    path: string;
+    /** out-of-box url like https://api.example.com/v0/core/target */
+    endpoint: string;
+    request: {
+        query: FieldDefinition[];
+    };
+    response: {
+        "200": FieldDefinition[];
+    };
+    manifestVersion: number;
+    lifecycle: ServiceLifecycle;
+    /** TODO contentType: e.g. application/json | application/octet-stream */
+    /** TODO auth / rate_limit / observability */
 }

package/src/shared/http/fetch-retry.ts

@@ -0,0 +1,145 @@
+import type { LoggerWithScope } from "../log/index";
+import { classifyNetworkError, formatNetworkError } from "../utils/network-error";
+
+function sleep(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/** Default HTTP statuses that trigger retry (429, 5xx). */
+export function isRetryableHttpStatus(status: number): boolean {
+    return status === 429 || status >= 500;
+}
+
+export type FetchInitFactory = () => RequestInit;
+
+export function requestHasBody(init: RequestInit): boolean {
+    return init.body != null;
+}
+
+export interface FetchRetryOptions {
+    label: string;
+    timeoutMs: number;
+    maxAttempts?: number;
+    retryBaseMs?: number;
+    maxBackoffMs?: number;
+    /** undici ProxyAgent or other fetch extension — typed loosely to avoid undici dependency. */
+    dispatcher?: unknown;
+    isRetryableStatus?: (status: number) => boolean;
+    /** When set, retry/success lines are logged via SDK logger. */
+    logger?: LoggerWithScope;
+    hint?: string;
+}
+
+function backoffMs(retryBaseMs: number, attempt: number, response?: Response, maxBackoffMs?: number): number {
+    const retryAfter = response?.headers.get("Retry-After");
+    if (retryAfter != null) {
+        const seconds = Number(retryAfter);
+        if (Number.isFinite(seconds) && seconds > 0) {
+            const delayMs = seconds * 1000;
+            return maxBackoffMs != null ? Math.min(delayMs, maxBackoffMs) : delayMs;
+        }
+    }
+
+    let delayMs = retryBaseMs * 2 ** (attempt - 1);
+    if (maxBackoffMs != null) {
+        delayMs = Math.min(delayMs, maxBackoffMs);
+    }
+    return delayMs;
+}
+
+async function fetchOnce(url: string, init: RequestInit, timeoutMs: number, dispatcher?: unknown): Promise<Response> {
+    const options: RequestInit & { dispatcher?: unknown } = {
+        ...init,
+        signal: AbortSignal.timeout(timeoutMs),
+    };
+    if (dispatcher != null) {
+        options.dispatcher = dispatcher;
+    }
+    return fetch(url, options);
+}
+
+export async function fetchWithRetry(
+    url: string,
+    initOrFactory: RequestInit | FetchInitFactory,
+    options: FetchRetryOptions,
+): Promise<Response> {
+    const maxAttempts = options.maxAttempts ?? 1;
+    const retryBaseMs = options.retryBaseMs ?? 2_000;
+    const isRetryableStatus = options.isRetryableStatus ?? isRetryableHttpStatus;
+    const buildInit = typeof initOrFactory === "function" ? initOrFactory : () => initOrFactory;
+
+    if (maxAttempts > 1 && typeof initOrFactory !== "function" && requestHasBody(initOrFactory)) {
+        throw new Error(`${options.label}: retry requires an init factory when request body may be consumed`);
+    }
+
+    let lastError: Error | null = null;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        try {
+            const response = await fetchOnce(url, buildInit(), options.timeoutMs, options.dispatcher);
+
+            if (!response.ok && isRetryableStatus(response.status) && attempt < maxAttempts) {
+                const delayMs = backoffMs(retryBaseMs, attempt, response, options.maxBackoffMs);
+                if (options.logger != null) {
+                    options.logger.warn("retrying after HTTP error", {
+                        topic: "fetch",
+                        data: {
+                            label: options.label,
+                            attempt,
+                            status: response.status,
+                            delayMs,
+                        },
+                    });
+                }
+                await sleep(delayMs);
+                continue;
+            }
+
+            if (attempt > 1 && options.logger != null) {
+                options.logger.info("request succeeded after retry", {
+                    topic: "fetch",
+                    data: { label: options.label, attempt },
+                });
+            }
+
+            return response;
+        } catch (error) {
+            const classified = classifyNetworkError(error);
+            lastError = new Error(formatNetworkError(error, options.label, { hint: options.hint }));
+
+            if (classified.retryable && attempt < maxAttempts) {
+                const delayMs = backoffMs(retryBaseMs, attempt, undefined, options.maxBackoffMs);
+                if (options.logger != null) {
+                    options.logger.warn("retrying after network error", {
+                        topic: "fetch",
+                        data: {
+                            label: options.label,
+                            attempt,
+                            maxAttempts,
+                            kind: classified.kind,
+                            code: classified.code,
+                            delayMs,
+                        },
+                    });
+                }
+                await sleep(delayMs);
+                continue;
+            }
+            throw lastError;
+        }
+    }
+
+    throw lastError ?? new Error(`${options.label}: request failed`);
+}
+
+export async function fetchBinaryWithRetry(
+    url: string,
+    init: RequestInit,
+    options: FetchRetryOptions,
+): Promise<ArrayBuffer> {
+    const response = await fetchWithRetry(url, init, options);
+    if (!response.ok) {
+        throw new Error(`${options.label}: HTTP ${response.status}`);
+    }
+    return response.arrayBuffer();
+}

package/src/shared/log/create-logger.ts

@@ -0,0 +1,51 @@
+import { type LoggerWithScope, type LogLevel, logManager } from "./log-manager";
+import { createScope, type LogScope, type LogScopePatch } from "./log-scope";
+
+type CreateLoggerLevelOption = {
+    /** Overrides global minimum level for this logger only. */
+    minLevel?: LogLevel;
+};
+
+/** Build scope from fields, then bind a logger. */
+export type CreateLoggerFromModuleInput = {
+    module: string;
+    traceId?: string;
+    traceParentId?: string | null;
+    labels?: Record<string, string>;
+} & CreateLoggerLevelOption;
+
+/** Bind a logger to an existing {@link LogScope}. */
+export type CreateLoggerFromScopeInput = {
+    scope: LogScope;
+} & CreateLoggerLevelOption;
+
+export type CreateLoggerInput = CreateLoggerFromModuleInput | CreateLoggerFromScopeInput;
+
+function isScopeInput(input: CreateLoggerInput): input is CreateLoggerFromScopeInput {
+    return "scope" in input;
+}
+
+/**
+ * Returns a scoped logger — one entry for all call sites.
+ *
+ * - `{ module, traceId?, labels?, … }` — creates a scope (API handlers, one-shot calls)
+ * - `{ scope, minLevel? }` — binds an existing scope (`createScope`, `patchScope`, …)
+ */
+export function createLogger(input: CreateLoggerInput): LoggerWithScope {
+    const { minLevel } = input;
+    const scopeOptions = minLevel != null ? { minLevel } : undefined;
+
+    if (isScopeInput(input)) {
+        return logManager.withScope(input.scope, scopeOptions).logger;
+    }
+
+    const scope = createScope({
+        module: input.module,
+        traceId: input.traceId?.trim() || logManager.generateTraceId(),
+        traceParentId: input.traceParentId,
+        labels: input.labels,
+    });
+    return logManager.withScope(scope, scopeOptions).logger;
+}
+
+export type { LogScopePatch };