@distilled.cloud/ovh 0.0.0 → 1.0.0-rc.9

package/src/errors.ts

@@ -0,0 +1,50 @@
+/**
+ * OVH-specific error types.
+ *
+ * Re-exports the common HTTP errors from core and adds the OVH fallback
+ * errors. Note the generated service modules additionally define their own
+ * per-status matcher classes (BadRequest/NotFound/…) for the statuses each
+ * operation declares — those share `_tag`s with the core classes here, so
+ * `catchTag` works against either.
+ */
+export {
+  BadGateway,
+  BadRequest,
+  Conflict,
+  ConfigError,
+  Forbidden,
+  GatewayTimeout,
+  InternalServerError,
+  Locked,
+  NotFound,
+  ServiceUnavailable,
+  TooManyRequests,
+  Unauthorized,
+  UnprocessableEntity,
+  HTTP_STATUS_MAP,
+  DEFAULT_ERRORS,
+  API_ERRORS,
+} from "@distilled.cloud/core/errors";
+export type { DefaultErrors } from "@distilled.cloud/core/errors";
+
+import * as Schema from "effect/Schema";
+import * as Category from "@distilled.cloud/core/category";
+
+/** Unknown OVH error — returned when nothing else matches the failure. */
+export class UnknownOvhError extends Schema.TaggedError<UnknownOvhError>()(
+  "UnknownOvhError",
+  {
+    code: Schema.optional(Schema.String),
+    message: Schema.optional(Schema.String),
+    body: Schema.Unknown,
+  },
+).pipe(Category.withServerError) {}
+
+/** Schema parse error wrapper. */
+export class OvhParseError extends Schema.TaggedError<OvhParseError>()(
+  "OvhParseError",
+  {
+    body: Schema.Unknown,
+    cause: Schema.Unknown,
+  },
+).pipe(Category.withParseError) {}

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * @distilled.cloud/ovh — OVHcloud API SDK for Effect.
+ *
+ * `./services` is generated by `scripts/generate.ts` from the Smithy models
+ * in `.generated-specs` (written by `scripts/convert.ts` from the OpenAPI
+ * specs). Everything else in this folder is hand-written.
+ *
+ * @example
+ * ```ts
+ * import * as Ovh from "@distilled.cloud/ovh";
+ *
+ * const servers = yield* Ovh.Services.vps.getVps({});
+ * ```
+ */
+export * from "./credentials.ts";
+export * from "./errors.ts";
+export * as T from "./traits.ts";
+export { OvhProtocol, type OvhOpError, type OvhOpContext } from "./protocol.ts";
+export { paginateCursor } from "./pagination.ts";
+export * as Retry from "./retry.ts";
+export * as Services from "./services/index.ts";

package/src/pagination.ts

@@ -0,0 +1,7 @@
+/**
+ * OVH pagination — hand-written.
+ *
+ * Generated operations that the converter stamps as cursor-paginated pass
+ * core's {@link paginateCursor} strategy to `API.makePaginated`.
+ */
+export { paginateCursor } from "@distilled.cloud/core/pagination";

package/src/protocol.ts

@@ -0,0 +1,86 @@
+/**
+ * OvhProtocol — hand-written.
+ *
+ * OVH speaks bearer-authenticated JSON REST (no response envelope), so the
+ * whole protocol is one `makeRestProtocol` call from `core/protocol-rest`:
+ *
+ *   request:  credentials → `Authorization: Bearer <access_token>` + base URL
+ *             (default https://eu.api.ovh.com/1.0), resolved from the calling
+ *             fiber on every request
+ *
+ *   response: 2xx JSON is the payload (sensitive members delivered as
+ *             `Redacted`); non-2xx `{ message, errorCode? | class? }` bodies
+ *             map to the operation's typed error classes by status, then the
+ *             shared HTTP-status classes, then {@link UnknownOvhError}.
+ */
+import * as Effect from "effect/Effect";
+import type * as Layer from "effect/Layer";
+import * as Redacted from "effect/Redacted";
+import type * as HttpClient from "effect/unstable/http/HttpClient";
+import type * as HttpClientError from "effect/unstable/http/HttpClientError";
+import type * as API from "@distilled.cloud/core/api";
+import {
+  makeRestProtocol,
+  type RestErrorEnvelope,
+} from "@distilled.cloud/core/protocol-rest";
+import type { API_ERRORS, ConfigError } from "@distilled.cloud/core/errors";
+import { Credentials, type Config } from "./credentials.ts";
+import { UnknownOvhError } from "./errors.ts";
+
+/**
+ * Error channel shared by every generated OVH operation. Generated service
+ * files annotate operations with `API.OperationMethod<I, O, OvhOpError,
+ * OvhOpContext>` explicitly so the compiler never infers these back out of
+ * the schema generics.
+ */
+export type OvhOpError =
+  | InstanceType<(typeof API_ERRORS)[number]>
+  | UnknownOvhError
+  | ConfigError
+  | HttpClientError.HttpClientError;
+
+/** Context (requirements) shared by every generated OVH operation. */
+export type OvhOpContext = Credentials | HttpClient.HttpClient;
+
+/**
+ * OVH error bodies are `{ message, errorCode? }` or `{ class, message }`.
+ */
+const errorEnvelope = (body: unknown): RestErrorEnvelope | undefined => {
+  if (body === null || typeof body !== "object") return undefined;
+  const b = body as Record<string, unknown>;
+  const message = typeof b.message === "string" ? b.message : undefined;
+  const code =
+    typeof b.errorCode === "string" || typeof b.errorCode === "number"
+      ? b.errorCode
+      : typeof b.class === "string"
+        ? b.class
+        : typeof b.code === "string" || typeof b.code === "number"
+          ? b.code
+          : undefined;
+  return { code, message };
+};
+
+export const OvhProtocol: Layer.Layer<API.Protocol> = makeRestProtocol<Config>({
+  // The Credentials service holds an effect — resolving it here (per
+  // request, on the calling fiber) picks up context-provided credentials.
+  credentials: Effect.gen(function* () {
+    const resolve = yield* Credentials;
+    return yield* resolve;
+  }),
+  baseUrl: (creds) => creds.apiBaseUrl,
+  headers: (creds) => ({
+    Authorization: `Bearer ${Redacted.value(creds.apiKey)}`,
+  }),
+  errorEnvelope,
+  unknownError: ({ code, message, body }) =>
+    new UnknownOvhError({
+      code:
+        typeof code === "string"
+          ? code
+          : code !== undefined
+            ? String(code)
+            : undefined,
+      message,
+      body,
+    }),
+});

package/src/retry.ts

@@ -0,0 +1,54 @@
+/**
+ * OVH retry configuration.
+ *
+ * Defines the per-SDK `Retry` Context.Service tag that generated operations
+ * wire into `API.make`. Callers can install a blanket retry policy at the
+ * layer level and have every OVH API call below it pick it up:
+ *
+ * @example
+ * ```ts
+ * import * as Ovh from "@distilled.cloud/ovh";
+ *
+ * myEffect.pipe(Ovh.Retry.transient);
+ * Effect.provide(myEffect, Layer.succeed(Ovh.Retry.Retry, customPolicy));
+ * ```
+ */
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import {
+  type Policy,
+  throttlingFactory,
+  transientFactory,
+} from "@distilled.cloud/core/retry";
+
+export {
+  type Options,
+  type Factory,
+  type Policy,
+  makeDefault,
+  jittered,
+  capped,
+  throttlingOptions,
+  transientOptions,
+  throttlingFactory,
+  transientFactory,
+} from "@distilled.cloud/core/retry";
+
+/** Context tag for configuring retry behavior of OVH API calls. */
+export class Retry extends Context.Service<Retry, Policy>()("OvhRetry") {}
+
+/** Provides a custom retry policy to every OVH API call below it. */
+export const policy = (optionsOrFactory: Policy) =>
+  Effect.provide(Layer.succeed(Retry, optionsOrFactory));
+
+/** Disables all automatic retries. */
+export const none = Effect.provide(
+  Layer.succeed(Retry, { while: () => false }),
+);
+
+/** Apply the throttling retry policy (retries throttling errors indefinitely). */
+export const throttling = policy(throttlingFactory);
+
+/** Apply the transient retry policy (retries all transient errors indefinitely). */
+export const transient = policy(transientFactory);