@segmentstream/ontology 0.0.0-stage → 0.92.1

package/dist/service/errors.d.ts

@@ -0,0 +1,145 @@
+import { Cause, Context, Effect, Schema, SchemaIssue } from "effect";
+import { HttpServerResponse } from "effect/unstable/http";
+import type { ValidationIssue } from "../runtime/errors.js";
+declare const RequestId_base: Context.ServiceClass<RequestId, "@segmentstream/ontology/RequestId", string>;
+/** The correlation id of the current request, in every error body and the `x-request-id` header. */
+export declare class RequestId extends RequestId_base {
+}
+declare const InvalidActionInput_base: Schema.Class<InvalidActionInput, Schema.TaggedStruct<"InvalidActionInput", {
+    readonly issues: Schema.$Array<Schema.Struct<{
+        readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Number]>>;
+        readonly message: Schema.String;
+    }>>;
+}>, Cause.YieldableError>;
+/** The action's input failed validation and the request was not `validateOnly`. */
+export declare class InvalidActionInput extends InvalidActionInput_base {
+}
+declare const InvalidRequestBody_base: Schema.Class<InvalidRequestBody, Schema.TaggedStruct<"InvalidRequestBody", {
+    readonly reason: Schema.Literals<readonly ["invalid_json", "invalid_request", "unsupported_media_type"]>;
+    readonly issues: Schema.$Array<Schema.Struct<{
+        readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Number]>>;
+        readonly message: Schema.String;
+    }>>;
+}>, Cause.YieldableError>;
+/** The body of an action request is not `{ input, options? }`. */
+export declare class InvalidRequestBody extends InvalidRequestBody_base {
+}
+declare const SignInCheckLimited_base: Schema.Class<SignInCheckLimited, Schema.TaggedStruct<"SignInCheckLimited", {
+    readonly retryAfterSeconds: Schema.Number;
+}>, Cause.YieldableError>;
+/** A client asked `POST /api/ontology/sign-in/check` too often; it may ask again after this. */
+export declare class SignInCheckLimited extends SignInCheckLimited_base {
+}
+declare const InvalidMetricQuery_base: Schema.Class<InvalidMetricQuery, Schema.TaggedStruct<"InvalidMetricQuery", {
+    readonly reason: Schema.String;
+}>, Cause.YieldableError>;
+/** A metric query the ontology cannot answer; the reason is written for the caller. */
+export declare class InvalidMetricQuery extends InvalidMetricQuery_base {
+}
+declare const ReadDenied_base: Schema.Class<ReadDenied, Schema.TaggedStruct<"ReadDenied", {
+    readonly permissions: Schema.$Array<Schema.String>;
+}>, Cause.YieldableError>;
+/** The caller lacks `<entity>:read` on entities a metric query reads: every such permission. */
+export declare class ReadDenied extends ReadDenied_base {
+}
+/**
+ * Why a scope cannot be applied to a metric query: it follows a path from `me` (`me_path`), is too
+ * large to send (`too_large`), SegmentStream cannot plan it in the warehouse (`unplannable`), or
+ * SegmentStream did not confirm it applied it (`unconfirmed`). A code, so that a workspace words it.
+ */
+export declare const ScopedMetricQueryReason: Schema.Literals<readonly ["me_path", "too_large", "unplannable", "unconfirmed"]>;
+export type ScopedMetricQueryReason = typeof ScopedMetricQueryReason.Type;
+declare const ScopedMetricQueryUnavailable_base: Schema.Class<ScopedMetricQueryUnavailable, Schema.TaggedStruct<"ScopedMetricQueryUnavailable", {
+    readonly entity: Schema.String;
+    readonly reason: Schema.optional<Schema.Literals<readonly ["me_path", "too_large", "unplannable", "unconfirmed"]>>;
+}>, Cause.YieldableError>;
+/**
+ * The caller reads an entity a metric query touches only within a scope the query cannot apply:
+ * answering would count or sum rows the caller's lists leave out. `reason` says why, when known.
+ */
+export declare class ScopedMetricQueryUnavailable extends ScopedMetricQueryUnavailable_base {
+}
+declare const MetricQueriesUnavailable_base: Schema.Class<MetricQueriesUnavailable, Schema.TaggedStruct<"MetricQueriesUnavailable", {}>, Cause.YieldableError>;
+/** The deployment has no workspace app credential: previews and local development. */
+export declare class MetricQueriesUnavailable extends MetricQueriesUnavailable_base {
+}
+declare const WarehouseReadUnavailable_base: Schema.Class<WarehouseReadUnavailable, Schema.TaggedStruct<"WarehouseReadUnavailable", {
+    readonly reason: Schema.Literals<readonly ["not_configured", "upstream", "limited"]>;
+    readonly retryAfterSeconds: Schema.optionalKey<Schema.Number>;
+    readonly cause: Schema.optionalKey<Schema.Unknown>;
+}>, Cause.YieldableError>;
+/** A warehouse observation could not be read; no database record is substituted. */
+export declare class WarehouseReadUnavailable extends WarehouseReadUnavailable_base {
+}
+declare const MetricQueryLimited_base: Schema.Class<MetricQueryLimited, Schema.TaggedStruct<"MetricQueryLimited", {
+    readonly retryAfterSeconds: Schema.Number;
+}>, Cause.YieldableError>;
+/** A principal ran more metric queries than its window allows; it may run more after this. */
+export declare class MetricQueryLimited extends MetricQueryLimited_base {
+}
+declare const MetricQueryUpstreamUnavailable_base: Schema.Class<MetricQueryUpstreamUnavailable, Schema.TaggedStruct<"MetricQueryUpstreamUnavailable", {
+    readonly reason: Schema.Literals<readonly ["unreachable", "timeout", "invalid_response", "credential_rejected", "upstream_misconfigured"]>;
+    readonly status: Schema.optionalKey<Schema.Number>;
+}>, Cause.YieldableError>;
+/**
+ * SegmentStream did not answer a metric query usably, or its answer faults the deployment rather than
+ * the caller. The operator log keeps the details; the caller learns only the reason.
+ */
+export declare class MetricQueryUpstreamUnavailable extends MetricQueryUpstreamUnavailable_base {
+}
+export interface ErrorBody {
+    readonly error: string;
+    readonly detail: string;
+    readonly requestId: string;
+    readonly [key: string]: unknown;
+}
+export interface ErrorResponse {
+    readonly status: number;
+    readonly body: ErrorBody;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export declare function toServerResponse(response: ErrorResponse): HttpServerResponse.HttpServerResponse;
+export declare function errorBodyForWire(body: ErrorBody): Readonly<Record<string, unknown>>;
+/** Issues of a schema failure, as `[{ path, message }]`. */
+export declare function schemaIssues(issue: SchemaIssue.Issue): Array<ValidationIssue>;
+/**
+ * `challenge` is the `WWW-Authenticate` value; the MCP server's names its OAuth metadata, which is
+ * how a client learns where members authorize it.
+ */
+export declare function unauthorized(requestId: string, detail: string, challenge?: string): ErrorResponse;
+/**
+ * The token is valid but the `invited` sign-in policy turns its holder away: nobody invited them.
+ * The detail is written for the person, since the app shows it.
+ */
+export declare function notInvited(requestId: string): ErrorResponse;
+/**
+ * A request that changes something came with the session cookie but not from the app's own pages.
+ * The cookie rides along with any request to the app's domain, so only its origin can vouch for it.
+ */
+export declare function crossOriginSession(requestId: string): ErrorResponse;
+/** The caller is authenticated but may not do this; the detail says why. */
+export declare function forbidden(requestId: string, detail: string): ErrorResponse;
+/** A client asked too often; it may ask again after `retryAfterSeconds`. */
+export declare function rateLimited(requestId: string, detail: string, retryAfterSeconds: number): ErrorResponse;
+/** The resource does not exist, or not for this caller; the detail says what to do. */
+export declare function notFound(requestId: string, detail: string): ErrorResponse;
+export declare function unavailable(requestId: string): ErrorResponse;
+/** File storage failed. The caller retries the same request; operators still log the cause. */
+export declare function storageUnavailable(requestId: string): ErrorResponse;
+/** A failure of the file storage provider, which is answered as retryable but still logged. */
+export declare function isStorageFailure(error: unknown): boolean;
+export declare function internalError(requestId: string): ErrorResponse;
+export declare function routeNotFound(requestId: string, suggestions?: ReadonlyArray<string>): ErrorResponse;
+/**
+ * The response for an expected failure, or `undefined` for anything else. Messages written for the
+ * caller (an action's rejection, schema issues about the request) are returned; everything else
+ * gets a fixed detail.
+ */
+export declare function expectedFailure(error: unknown, requestId: string): ErrorResponse | undefined;
+/**
+ * Turns a failed request into a response. Expected failures map to their status; anything else is
+ * logged with the full cause and answered with a sanitized 500 that carries only the request id.
+ * Interruptions stay interruptions: the client is gone.
+ */
+export declare function failureResponse(cause: Cause.Cause<unknown>, requestId: string): Effect.Effect<HttpServerResponse.HttpServerResponse>;
+export {};