availsync 0.1.0

package/packages/node/src/index.ts

@@ -0,0 +1,402 @@
+export type ResourceType = 'repo' | 'project';
+
+export type FetchLike = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export type AvailsyncClientOptions = {
+  apiKey: string;
+  agentId: string;
+  baseUrl?: string;
+  timeoutMs?: number;
+  fetch?: FetchLike;
+};
+
+export type WorkStartOptions = {
+  resource: string;
+  durationMinutes?: number;
+  reason?: string;
+  idempotencyKey?: string;
+  metadata?: Record<string, unknown>;
+  signal?: AbortSignal;
+};
+
+export type WorkExtendOptions = {
+  durationMinutes?: number;
+  signal?: AbortSignal;
+};
+
+export type WorkFinishOptions = {
+  outcome?: string;
+  reason?: string;
+  metadata?: Record<string, unknown>;
+  signal?: AbortSignal;
+};
+
+export type ParsedResource = {
+  resourceType: ResourceType;
+  resourceKey: string;
+};
+
+export type WorkClaim = {
+  id: string;
+  [key: string]: unknown;
+};
+
+export type ShadowDecision = {
+  action: 'skip_run';
+  reason?: string;
+  retry_after?: string | null;
+  blocking_claim?: Record<string, unknown> | null;
+  rule_applied?: string | null;
+  winning_claim_id?: string | null;
+  [key: string]: unknown;
+};
+
+export type WorkRunStartProceed = {
+  action: 'proceed';
+  claim: WorkClaim | null;
+  resource?: Record<string, unknown>;
+  reason?: string;
+  retry_after?: null;
+  blocking_claim?: null;
+  shadow_mode?: boolean;
+  would_have_blocked?: boolean;
+  shadow_decision?: ShadowDecision | null;
+  [key: string]: unknown;
+};
+
+export type WorkRunStartSkip = {
+  action: 'skip_run';
+  claim?: null;
+  resource?: Record<string, unknown>;
+  reason: string;
+  retry_after?: string | null;
+  blocking_claim?: Record<string, unknown> | null;
+  [key: string]: unknown;
+};
+
+export type WorkRunStartResult = WorkRunStartProceed | WorkRunStartSkip;
+
+export type WorkRunExtendResult = {
+  action: 'extended';
+  claim: WorkClaim;
+  [key: string]: unknown;
+};
+
+export type WorkRunFinishResult = {
+  action: 'finished' | 'already_finished';
+  claim: WorkClaim;
+  [key: string]: unknown;
+};
+
+export type WithClaimSkipResult = {
+  action: 'skip_run';
+  reason: string;
+  retryAfter: string | null;
+  blockingClaim: Record<string, unknown> | null;
+};
+
+export type WithClaimProceedResult<T> = {
+  action: 'proceed';
+  claim: GuardedWorkClaim | null;
+  result: T;
+  shadowMode: boolean;
+  wouldHaveBlocked: boolean;
+  shadowDecision: ShadowDecision | null;
+};
+
+export type GuardedWorkClaim = WorkClaim & {
+  extend(options?: WorkExtendOptions): Promise<WorkRunExtendResult>;
+  finish(options?: WorkFinishOptions): Promise<WorkRunFinishResult>;
+};
+
+export type WithClaimContext = {
+  claim: GuardedWorkClaim | null;
+  shadow: {
+    mode: boolean;
+    wouldHaveBlocked: boolean;
+    decision: ShadowDecision | null;
+  };
+};
+
+export class AvailsyncError extends Error {
+  readonly code: string;
+  readonly status: number | null;
+  readonly details?: unknown;
+
+  constructor(input: {
+    code: string;
+    message: string;
+    status?: number | null;
+    details?: unknown;
+  }) {
+    super(input.message);
+    this.name = 'AvailsyncError';
+    this.code = input.code;
+    this.status = input.status ?? null;
+    this.details = input.details;
+  }
+}
+
+export function parseResource(resource: string): ParsedResource {
+  const separator = resource.indexOf(':');
+  if (separator <= 0 || separator === resource.length - 1) {
+    throw new AvailsyncError({
+      code: 'invalid_resource',
+      message: 'Resource must use "repo:owner/name" or "project:key" format.',
+    });
+  }
+
+  const resourceType = resource.slice(0, separator);
+  const resourceKey = resource.slice(separator + 1);
+  if ((resourceType !== 'repo' && resourceType !== 'project') || resourceKey.trim() !== resourceKey || !resourceKey) {
+    throw new AvailsyncError({
+      code: 'invalid_resource',
+      message: 'Resource must use "repo:owner/name" or "project:key" format.',
+    });
+  }
+
+  return { resourceType, resourceKey };
+}
+
+export function createAvailsyncClient(options: AvailsyncClientOptions) {
+  if (!options.apiKey) {
+    throw new AvailsyncError({ code: 'missing_api_key', message: 'apiKey is required.' });
+  }
+  if (!options.agentId) {
+    throw new AvailsyncError({ code: 'missing_agent_id', message: 'agentId is required.' });
+  }
+
+  const baseUrl = (options.baseUrl ?? 'https://availsync.dev').replace(/\/+$/, '');
+  const timeoutMs = options.timeoutMs ?? 30_000;
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (!fetchImpl) {
+    throw new AvailsyncError({
+      code: 'fetch_unavailable',
+      message: 'Global fetch is unavailable. Use Node 18+ or pass a fetch implementation.',
+    });
+  }
+
+  async function request<T>(path: string, init: RequestInit, signal?: AbortSignal): Promise<T> {
+    const abort = createRequestAbort(timeoutMs, signal);
+    let response: Response;
+    try {
+      response = await fetchImpl(`${baseUrl}${path}`, { ...init, signal: abort.signal });
+    } catch (error) {
+      if (abort.timedOut()) {
+        throw new AvailsyncError({
+          code: 'timeout',
+          message: 'Timed out calling Availsync.',
+          details: { timeout_ms: timeoutMs },
+        });
+      }
+      if (signal?.aborted) {
+        throw new AvailsyncError({
+          code: 'aborted',
+          message: 'Availsync request was aborted.',
+        });
+      }
+      throw new AvailsyncError({
+        code: 'network_error',
+        message: 'Network error calling Availsync.',
+        details: error instanceof Error ? { message: error.message } : undefined,
+      });
+    } finally {
+      abort.cleanup();
+    }
+
+    const body = await parseJson(response);
+    if (!response.ok) {
+      const errorBody = asRecord(body);
+      throw new AvailsyncError({
+        code: stringFrom(errorBody.error) ?? `http_${response.status}`,
+        message: stringFrom(errorBody.message) ?? 'Availsync API request failed.',
+        status: response.status,
+        details: body,
+      });
+    }
+    return body as T;
+  }
+
+  function headers(idempotencyKey?: string): Record<string, string> {
+    return {
+      Authorization: `Bearer ${options.apiKey}`,
+      'Content-Type': 'application/json',
+      ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}),
+    };
+  }
+
+  async function start(input: WorkStartOptions): Promise<WorkRunStartResult> {
+    const resource = parseResource(input.resource);
+    return request<WorkRunStartResult>('/v1/work/run/start', {
+      method: 'POST',
+      headers: headers(input.idempotencyKey),
+      body: JSON.stringify({
+        agent_id: options.agentId,
+        resource_type: resource.resourceType,
+        resource_key: resource.resourceKey,
+        duration_minutes: input.durationMinutes,
+        reason: input.reason,
+        metadata: input.metadata,
+        client_name: '@availsync/node',
+      }),
+    }, input.signal);
+  }
+
+  async function extend(claimId: string, input: WorkExtendOptions = {}): Promise<WorkRunExtendResult> {
+    return request<WorkRunExtendResult>('/v1/work/run/extend', {
+      method: 'POST',
+      headers: headers(),
+      body: JSON.stringify({
+        claim_id: claimId,
+        duration_minutes: input.durationMinutes,
+        client_name: '@availsync/node',
+      }),
+    }, input.signal);
+  }
+
+  async function finish(claimId: string, input: WorkFinishOptions = {}): Promise<WorkRunFinishResult> {
+    return request<WorkRunFinishResult>('/v1/work/run/finish', {
+      method: 'POST',
+      headers: headers(),
+      body: JSON.stringify({
+        claim_id: claimId,
+        outcome: input.outcome,
+        reason: input.reason,
+        metadata: input.metadata,
+        client_name: '@availsync/node',
+      }),
+    }, input.signal);
+  }
+
+  function guardedClaim(claim: WorkClaim): GuardedWorkClaim {
+    return {
+      ...claim,
+      extend: (input?: WorkExtendOptions) => extend(claim.id, input),
+      finish: (input?: WorkFinishOptions) => finish(claim.id, input),
+    };
+  }
+
+  async function withClaim<T>(
+    resource: string,
+    input: Omit<WorkStartOptions, 'resource'>,
+    fn: (context: WithClaimContext) => Promise<T> | T,
+  ): Promise<WithClaimSkipResult | WithClaimProceedResult<T>> {
+    const startResult = await start({ ...input, resource });
+    if (startResult.action === 'skip_run') {
+      return {
+        action: 'skip_run',
+        reason: startResult.reason,
+        retryAfter: startResult.retry_after ?? null,
+        blockingClaim: startResult.blocking_claim ?? null,
+      };
+    }
+
+    const shadowMode = Boolean(startResult.shadow_mode);
+    const wouldHaveBlocked = Boolean(startResult.would_have_blocked);
+    const shadowDecision = startResult.shadow_decision ?? null;
+    if (!startResult.claim) {
+      const result = await fn({
+        claim: null,
+        shadow: { mode: shadowMode, wouldHaveBlocked, decision: shadowDecision },
+      });
+      return {
+        action: 'proceed',
+        claim: null,
+        result,
+        shadowMode,
+        wouldHaveBlocked,
+        shadowDecision,
+      };
+    }
+
+    const claim = guardedClaim(startResult.claim);
+    let result: T;
+    try {
+      result = await fn({
+        claim,
+        shadow: { mode: shadowMode, wouldHaveBlocked, decision: shadowDecision },
+      });
+    } catch (error) {
+      try {
+        await finish(claim.id, { outcome: 'error' });
+      } catch {
+        // Preserve the original agent error; finish failures are visible in Availsync Activity.
+      }
+      throw error;
+    }
+
+    await finish(claim.id, { outcome: 'finished' });
+    return { action: 'proceed', claim, result, shadowMode, wouldHaveBlocked, shadowDecision };
+  }
+
+  return {
+    work: {
+      start,
+      extend,
+      finish,
+      withClaim,
+    },
+  };
+}
+
+function createRequestAbort(timeoutMs: number, external?: AbortSignal): {
+  signal: AbortSignal;
+  cleanup(): void;
+  timedOut(): boolean;
+} {
+  const controller = new AbortController();
+  let didTimeout = false;
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+
+  if (timeoutMs > 0) {
+    timeout = setTimeout(() => {
+      didTimeout = true;
+      controller.abort();
+    }, timeoutMs);
+  }
+
+  const abortFromExternal = () => controller.abort();
+  if (external) {
+    if (external.aborted) {
+      controller.abort();
+    } else {
+      external.addEventListener('abort', abortFromExternal, { once: true });
+    }
+  }
+
+  return {
+    signal: controller.signal,
+    cleanup() {
+      if (timeout) clearTimeout(timeout);
+      external?.removeEventListener('abort', abortFromExternal);
+    },
+    timedOut() {
+      return didTimeout;
+    },
+  };
+}
+
+async function parseJson(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!text) return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new AvailsyncError({
+      code: 'invalid_json',
+      message: 'Availsync API returned invalid JSON.',
+      status: response.status,
+    });
+  }
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
+}
+
+function stringFrom(value: unknown): string | null {
+  return typeof value === 'string' ? value : null;
+}

package/packages/node/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "declaration": true,
+    "sourceMap": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.ts", "dist"]
+}

package/packages/node/tsconfig.test.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "types": ["node", "jest"],
+    "declaration": false,
+    "declarationMap": false,
+    "sourceMap": false
+  },
+  "include": ["src/**/*.ts"]
+}