/**
 * DataGuard API client — server-only.
 *
 * This file is the single place to look for "how do I call the Sidian
 * DataGuard org API from a Node/Next.js backend". Copy it into your own
 * project and you're set.
 *
 * Every function takes a `Creds` as its first argument. That is deliberate,
 * and it is the one thing worth copying along with the rest: this client
 * reads no environment variable and holds no ambient credential, so there is
 * no default identity for a call site to fall back on by forgetting
 * something. A missing credential is a compile error here, not a request
 * that silently goes out as somebody else.
 *
 * In your own backend you will likely load the key from an env var once, at
 * the edge of your system, and pass it down. Do that where you can see it.
 *
 * All endpoints are `POST` against `https://api.sidian.io/org/<slug>/...`.
 */

import "server-only";

/**
 * The two things every call needs.
 *
 * `key` is a `dg_live_` API key issued in the DataGuard admin portal under
 * API Integration. `slug` is your organization slug — the `<slug>` segment
 * of the API URL. They must agree: DataGuard rejects a key whose org does
 * not match the slug in the path (`SLUG_MISMATCH`), which is what stops a
 * leaked key being pointed at somebody else's organization.
 */
export type Creds = {
  /** `dg_live_…` API key. Never log this, never put it in a URL. */
  key: string;
  /** Organization slug, e.g. `acme-corp`. */
  slug: string;
};

function baseUrl(creds: Creds): string {
  return `https://api.sidian.io/org/${encodeURIComponent(creds.slug)}`;
}

function authHeaders(creds: Creds): Record<string, string> {
  return { Authorization: `Bearer ${creds.key}` };
}

// ─── Request shapes ──────────────────────────────────────────────────────

/**
 * Content to analyze. `text` and `url` variants also exist; this app uses
 * `content` (inline base64 upload) for small files and `multipart` (upload
 * session handle) for anything larger than a few MiB — see §10 of the
 * DataGuard API docs.
 */
export type Source =
  | {
      type: "content";
      base64Content: string;
      filename: string;
      mimeType: string;
    }
  | {
      type: "multipart";
      uploadId: string;
    };

/** One REDACT/EXCLUDE rule inside `rules.pdf[]` for `/redact`. */
export type PdfRule = {
  action: "REDACT" | "EXCLUDE";
  target: "WORDS" | "PARAGRAPHS" | "PAGES";
  text?: string;
  pages?: number[];
};

// ─── Response shapes ─────────────────────────────────────────────────────

/** One category entry in `/analyze/review`. RETAIN-action entities are omitted by the API. */
export type ReviewItem = {
  category: string;
  action: string;
  reference: string;
  items: string[];
  recommendation?: string;
};

export type ReviewResponse = {
  review: ReviewItem[];
  summary: string;
  stats: Record<string, number>;
};

/** `/scan` returns raw NER — an object keyed by entity type (e.g. "PERSON_NAME", "SSN"). */
export type ScanEntity = {
  action?: string;
  reference?: string;
  items: string[];
};

export type ScanResponse = {
  entities: Record<string, ScanEntity>;
  summary?: string;
  stats: { entitiesFound: number; processingTimeMs: number };
};

/** `/redact` and `/analyze/auto` both return the redacted file as base64 plus stats. */
export type RedactResponse = {
  base64Content: string;
  filename: string;
  mimeType: string;
  entities: Record<string, ScanEntity> | unknown;
  summary: string;
  stats: Record<string, number>;
};

/** `/analyze/auto` response shape matches `/redact`. */
export type AutoResponse = RedactResponse;

// ─── Multipart upload shapes ─────────────────────────────────────────────

/** `POST /uploads` response — opens a session. */
export type UploadInitResponse = {
  uploadId: string;
  partSize: number;
  minPartSize: number;
  maxParts: number;
  expiresAt: string;
};

/** `PUT /uploads/{uploadId}/parts/{partNumber}` response. */
export type UploadPartResponse = {
  partNumber: number;
  etag: string;
  size: number;
};

/** `POST /uploads/{uploadId}/complete` response. Returns a reusable `source`. */
export type UploadCompleteResponse = {
  uploadId: string;
  filename: string;
  size: number;
  mimeType: string;
  source: { type: "multipart"; uploadId: string };
};

// ─── Transport ───────────────────────────────────────────────────────────

/**
 * Error codes DataGuard returns that a caller can act on. Anything outside
 * this set is collapsed to a generic message before it reaches a browser.
 *
 * The reason is narrow and worth stating: an upstream error body is written
 * for an operator, not for whoever is looking at your page. It can carry
 * internal identifiers, and a validation error can echo back a fragment of
 * the document that caused it. Forwarding it verbatim turns your proxy into
 * a disclosure channel for someone else's service.
 */
const FORWARDABLE_ERROR_CODES = new Set([
  "SLUG_MISMATCH",
  "SUBSCRIPTION_INACTIVE",
  "PLAN_UPGRADE_REQUIRED",
  "ORG_NOT_FOUND",
  "TOO_LARGE_FOR_ANALYSIS",
  "INVALID_PART_NUMBER",
  "UPLOAD_NOT_FOUND",
  "UPLOAD_EXPIRED",
]);

/** An upstream failure, reduced to what is safe to show a caller. */
export class DataGuardError extends Error {
  readonly status: number;
  /** A `FORWARDABLE_ERROR_CODES` member, or `null` when the cause was not one. */
  readonly code: string | null;

  constructor(status: number, code: string | null, message: string) {
    super(message);
    this.name = "DataGuardError";
    this.status = status;
    this.code = code;
  }
}

async function throwUpstream(res: Response, label: string): Promise<never> {
  let code: string | null = null;
  try {
    const body = (await res.json()) as { error?: unknown };
    if (typeof body.error === "string" && FORWARDABLE_ERROR_CODES.has(body.error)) {
      code = body.error;
    }
  } catch {
    // A non-JSON body tells us nothing we are willing to repeat.
  }

  const message =
    code === "SLUG_MISMATCH"
      ? "This API key belongs to a different organization than the slug you entered."
      : code === "SUBSCRIPTION_INACTIVE"
        ? "This organization's DataGuard subscription is not active."
        : code === "PLAN_UPGRADE_REQUIRED"
          ? "The DataGuard API requires the Business plan or higher."
          : code
            ? `DataGuard rejected the ${label} request: ${code}.`
            : res.status === 401 || res.status === 403
              ? "DataGuard rejected this API key."
              : `DataGuard ${label} failed (HTTP ${res.status}).`;

  throw new DataGuardError(res.status, code, message);
}

async function dataguardPost<T>(
  creds: Creds,
  path: string,
  body: unknown,
  label: string,
): Promise<T> {
  const res = await fetch(`${baseUrl(creds)}${path}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      ...authHeaders(creds),
    },
    body: JSON.stringify(body),
  });
  if (!res.ok) await throwUpstream(res, label);
  return res.json() as Promise<T>;
}

// ─── Endpoints ───────────────────────────────────────────────────────────

/**
 * `POST /analyze/review` — full analysis returning structured review feedback.
 * Per-entity `action` + policy `reference` + human-readable `recommendation`.
 * Does not mutate the file. Use when you want a human to pick what to redact.
 */
export async function review(creds: Creds, source: Source): Promise<ReviewResponse> {
  return dataguardPost<ReviewResponse>(creds, "/analyze/review", { source }, "review");
}

/**
 * `POST /redact` — pure rule-based redaction. Applies `rules` to the uploaded
 * file with no NER or policy analysis. Returns the redacted file as base64.
 * Supports PDF/DOCX/PPTX (via `rules.pdf[]`) and XLSX/XLS (via `rules.xlsx[]`).
 */
export async function redact(
  creds: Creds,
  source: Source,
  rules: { pdf?: PdfRule[] },
): Promise<RedactResponse> {
  return dataguardPost<RedactResponse>(creds, "/redact", { source, rules }, "redact");
}

/**
 * `POST /analyze/auto` — full analysis + automatic redaction in one call.
 * Runs NER + policy, auto-generates rules from REDACT-action entities, and
 * returns the redacted file as base64. The one-shot version of `review`→`redact`.
 */
export async function auto(creds: Creds, source: Source): Promise<AutoResponse> {
  return dataguardPost<AutoResponse>(creds, "/analyze/auto", { source }, "auto");
}

// ─── Multipart upload helpers ────────────────────────────────────────────

/**
 * `POST /uploads` — open a multipart session. Use for files larger than a
 * few MiB. DataGuard returns an `uploadId` plus the `partSize` to chunk
 * against. Pass the `uploadId` back into any content endpoint as
 * `source: { type: "multipart", uploadId }` once `completeUpload` succeeds.
 */
export async function initiateUpload(
  creds: Creds,
  input: {
    filename: string;
    mimeType?: string;
    size?: number;
    partSize?: number;
  },
): Promise<UploadInitResponse> {
  const res = await fetch(`${baseUrl(creds)}/uploads`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      ...authHeaders(creds),
    },
    body: JSON.stringify(input),
  });
  if (!res.ok) await throwUpstream(res, "initiateUpload");
  return res.json() as Promise<UploadInitResponse>;
}

/**
 * `PUT /uploads/{uploadId}/parts/{partNumber}` — stream a single part.
 * Body is raw binary bytes; `body` may be a `ReadableStream` (streamed
 * straight from the client request) or a `BodyInit` buffer.
 *
 * `contentLength` should be set when `body` is a stream — fetch can't infer
 * the length of a half-duplex stream, and DataGuard rejects parts that
 * don't declare a length.
 */
export async function uploadPart(
  creds: Creds,
  uploadId: string,
  partNumber: number,
  body: BodyInit,
  contentLength?: number,
): Promise<UploadPartResponse> {
  const headers: Record<string, string> = {
    "Content-Type": "application/octet-stream",
    ...authHeaders(creds),
  };
  if (contentLength !== undefined) headers["Content-Length"] = String(contentLength);

  const init: RequestInit & { duplex?: "half" } = {
    method: "PUT",
    headers,
    body,
  };
  // Required when streaming a ReadableStream as the request body on Node.
  if (body instanceof ReadableStream) init.duplex = "half";

  const res = await fetch(`${baseUrl(creds)}/uploads/${uploadId}/parts/${partNumber}`, init);
  if (!res.ok) await throwUpstream(res, "uploadPart");
  return res.json() as Promise<UploadPartResponse>;
}

/**
 * `POST /uploads/{uploadId}/complete` — finalize and produce a reusable
 * `source` handle. `parts` must be the full `{ partNumber, etag }` list.
 */
export async function completeUpload(
  creds: Creds,
  uploadId: string,
  parts: { partNumber: number; etag: string }[],
): Promise<UploadCompleteResponse> {
  const res = await fetch(`${baseUrl(creds)}/uploads/${uploadId}/complete`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      ...authHeaders(creds),
    },
    body: JSON.stringify({ parts }),
  });
  if (!res.ok) await throwUpstream(res, "completeUpload");
  return res.json() as Promise<UploadCompleteResponse>;
}

/**
 * `DELETE /uploads/{uploadId}` — abort a session and release scratch space.
 * Idempotent if the session isn't currently being consumed.
 */
export async function abortUpload(creds: Creds, uploadId: string): Promise<void> {
  const res = await fetch(`${baseUrl(creds)}/uploads/${uploadId}`, {
    method: "DELETE",
    headers: authHeaders(creds),
  });
  if (!res.ok && res.status !== 204) await throwUpstream(res, "abortUpload");
}

/**
 * `POST /scan` — raw named-entity recognition. Returns every detected entity
 * keyed by entity type, with no policy evaluation or file mutation. Use when
 * you just want to know what's in the document.
 */
export async function scan(creds: Creds, source: Source): Promise<ScanResponse> {
  const raw = await dataguardPost<{
    entities: Record<string, ScanEntity | string[]>;
    summary: string;
    stats: { entitiesFound: number; processingTimeMs: number };
  }>(creds, "/scan", { source }, "scan");

  // Tolerate both `{ PERSON_NAME: { items: [...] } }` and `{ PERSON_NAME: [...] }` shapes.
  const entities: Record<string, ScanEntity> = {};
  for (const [type, value] of Object.entries(raw.entities ?? {})) {
    entities[type] = Array.isArray(value) ? { items: value } : value;
  }
  return { ...raw, entities };
}
Auto-Redact

Source code for your stack
