@effect-uai/fal 0.13.0

package/dist/codec.mjs

@@ -0,0 +1,73 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import { Array, Effect, Match, Option, Schema, pipe } from "effect";
+import * as AiError from "@effect-uai/core/AiError";
+//#region src/codec.ts
+var codec_exports = /* @__PURE__ */ __exportAll({
+	PROVIDER: () => "fal",
+	httpError: () => httpError,
+	missingImageField: () => missingImageField,
+	transportFailure: () => transportFailure
+});
+const PROVIDER = "fal";
+const transportFailure = (cause) => new AiError.Unavailable({
+	provider: "fal",
+	raw: cause
+});
+const Detail = Schema.Struct({
+	loc: Schema.optional(Schema.Array(Schema.Unknown)),
+	msg: Schema.optional(Schema.String),
+	type: Schema.optional(Schema.String)
+});
+/** Wrapped in `detail` off the gateway, bare off the runner. */
+const WireError = Schema.Union([Schema.Struct({ detail: Schema.Array(Detail) }), Schema.Array(Detail)]);
+const decodeWireError = Schema.decodeUnknownEffect(Schema.fromJsonString(WireError));
+const detailsOf = (wire) => "detail" in wire ? wire.detail : wire;
+/** The one refusal `type` fal documents; every other type is a bad field. */
+const CONTENT_POLICY = "content_policy_violation";
+const refusalOf = (wire, raw) => pipe(detailsOf(wire), Array.findFirst((detail) => detail.type === CONTENT_POLICY), Option.map((detail) => new AiError.ContentFiltered({
+	provider: "fal",
+	...detail.msg !== void 0 && { reason: detail.msg },
+	raw
+})));
+const statusError = (status, body) => Match.value(status).pipe(Match.when(429, () => new AiError.RateLimited({
+	provider: "fal",
+	raw: body
+})), Match.whenOr(408, 504, () => new AiError.Timeout({
+	provider: "fal",
+	raw: body
+})), Match.when(401, () => new AiError.AuthFailed({
+	provider: "fal",
+	subtype: "auth",
+	raw: body
+})), Match.when(403, () => new AiError.AuthFailed({
+	provider: "fal",
+	subtype: "permission",
+	raw: body
+})), Match.when(402, () => new AiError.AuthFailed({
+	provider: "fal",
+	subtype: "billing",
+	raw: body
+})), Match.when(413, () => new AiError.ContextLengthExceeded({
+	provider: "fal",
+	raw: body
+})), Match.when((n) => n >= 500, (n) => new AiError.Unavailable({
+	provider: "fal",
+	status: n,
+	raw: body
+})), Match.orElse(() => new AiError.InvalidRequest({
+	provider: "fal",
+	raw: body
+})));
+/** Never fails: the returned error is the value. */
+const httpError = (status, body) => decodeWireError(body).pipe(Effect.map((wire) => Option.getOrElse(refusalOf(wire, body), () => statusError(status, body))), Effect.orElseSucceed(() => statusError(status, body)));
+/** `image_url`, `image_urls`, `input_image_urls`, `reference_image_url`, … */
+const IMAGE_FIELD = /^[a-z_]*image[a-z_]*_urls?$/;
+/**
+* The reference field this endpoint asked for, if it rejected the request
+* for want of one. `Effect` only because the decode is; it never fails.
+*/
+const missingImageField = (body) => decodeWireError(body).pipe(Effect.map((wire) => pipe(detailsOf(wire), Array.filter((detail) => detail.type === "missing"), Array.map((detail) => detail.loc?.[1]), Array.findFirst((name) => typeof name === "string" && IMAGE_FIELD.test(name)))), Effect.orElseSucceed(() => Option.none()));
+//#endregion
+export { PROVIDER, httpError, missingImageField, codec_exports as t, transportFailure };
+
+//# sourceMappingURL=codec.mjs.map

package/dist/codec.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.mjs","names":["Arr"],"sources":["../src/codec.ts"],"sourcesContent":["import { Array as Arr, Effect, Match, Option, Schema, pipe } from \"effect\"\nimport * as AiError from \"@effect-uai/core/AiError\"\n\nexport const PROVIDER = \"fal\"\n\nexport const transportFailure = (cause: unknown): AiError.AiError =>\n  new AiError.Unavailable({ provider: PROVIDER, raw: cause })\n\n// ---------------------------------------------------------------------------\n// Errors\n//\n// fal validates request bodies with Pydantic, so a rejected field and a\n// refused prompt arrive the same way: 422 with a `detail` array. The entry's\n// `type` is what separates them. Errors that carry `detail` as a plain\n// string (a missing app, a bad key) fail this decode and fall through to the\n// status mapping, which is where they belong.\n//\n// Reference: https://fal.ai/docs/model-apis/errors\n// ---------------------------------------------------------------------------\n\nconst Detail = Schema.Struct({\n  loc: Schema.optional(Schema.Array(Schema.Unknown)),\n  msg: Schema.optional(Schema.String),\n  type: Schema.optional(Schema.String),\n})\ntype Detail = typeof Detail.Type\n\n/** Wrapped in `detail` off the gateway, bare off the runner. */\nconst WireError = Schema.Union([\n  Schema.Struct({ detail: Schema.Array(Detail) }),\n  Schema.Array(Detail),\n])\ntype WireError = typeof WireError.Type\n\nconst decodeWireError = Schema.decodeUnknownEffect(Schema.fromJsonString(WireError))\n\nconst detailsOf = (wire: WireError): ReadonlyArray<Detail> =>\n  \"detail\" in wire ? wire.detail : wire\n\n/** The one refusal `type` fal documents; every other type is a bad field. */\nconst CONTENT_POLICY = \"content_policy_violation\"\n\nconst refusalOf = (wire: WireError, raw: string): Option.Option<AiError.AiError> =>\n  pipe(\n    detailsOf(wire),\n    Arr.findFirst((detail) => detail.type === CONTENT_POLICY),\n    Option.map(\n      (detail) =>\n        new AiError.ContentFiltered({\n          provider: PROVIDER,\n          ...(detail.msg !== undefined && { reason: detail.msg }),\n          raw,\n        }),\n    ),\n  )\n\nconst statusError = (status: number, body: string): AiError.AiError =>\n  Match.value(status).pipe(\n    Match.when(\n      429,\n      (): AiError.AiError => new AiError.RateLimited({ provider: PROVIDER, raw: body }),\n    ),\n    Match.whenOr(\n      408,\n      504,\n      (): AiError.AiError => new AiError.Timeout({ provider: PROVIDER, raw: body }),\n    ),\n    Match.when(\n      401,\n      (): AiError.AiError =>\n        new AiError.AuthFailed({ provider: PROVIDER, subtype: \"auth\", raw: body }),\n    ),\n    Match.when(\n      403,\n      (): AiError.AiError =>\n        new AiError.AuthFailed({ provider: PROVIDER, subtype: \"permission\", raw: body }),\n    ),\n    Match.when(\n      402,\n      (): AiError.AiError =>\n        new AiError.AuthFailed({ provider: PROVIDER, subtype: \"billing\", raw: body }),\n    ),\n    Match.when(\n      413,\n      (): AiError.AiError => new AiError.ContextLengthExceeded({ provider: PROVIDER, raw: body }),\n    ),\n    Match.when(\n      (n) => n >= 500,\n      (n): AiError.AiError => new AiError.Unavailable({ provider: PROVIDER, status: n, raw: body }),\n    ),\n    Match.orElse(\n      (): AiError.AiError => new AiError.InvalidRequest({ provider: PROVIDER, raw: body }),\n    ),\n  )\n\n/** Never fails: the returned error is the value. */\nexport const httpError = (status: number, body: string): Effect.Effect<AiError.AiError> =>\n  decodeWireError(body).pipe(\n    Effect.map((wire) => Option.getOrElse(refusalOf(wire, body), () => statusError(status, body))),\n    Effect.orElseSucceed(() => statusError(status, body)),\n  )\n\n// ---------------------------------------------------------------------------\n// Reference-field discovery\n//\n// Endpoints spell the reference field four different ways and the id does\n// not say which. Rather than table fal's catalogue, read the answer off\n// the endpoint's own validation error: a `missing` entry names the field\n// it wanted in `loc`.\n// ---------------------------------------------------------------------------\n\n/** `image_url`, `image_urls`, `input_image_urls`, `reference_image_url`, … */\nconst IMAGE_FIELD = /^[a-z_]*image[a-z_]*_urls?$/\n\n/**\n * The reference field this endpoint asked for, if it rejected the request\n * for want of one. `Effect` only because the decode is; it never fails.\n */\nexport const missingImageField = (body: string): Effect.Effect<Option.Option<string>> =>\n  decodeWireError(body).pipe(\n    Effect.map((wire) =>\n      pipe(\n        detailsOf(wire),\n        Arr.filter((detail) => detail.type === \"missing\"),\n        Arr.map((detail) => detail.loc?.[1]),\n        Arr.findFirst((name): name is string => typeof name === \"string\" && IMAGE_FIELD.test(name)),\n      ),\n    ),\n    Effect.orElseSucceed(() => Option.none<string>()),\n  )\n"],"mappings":";;;;;;;;;;AAGA,MAAa,WAAW;AAExB,MAAa,oBAAoB,UAC/B,IAAI,QAAQ,YAAY;CAAE,UAAA;CAAoB,KAAK;AAAM,CAAC;AAc5D,MAAM,SAAS,OAAO,OAAO;CAC3B,KAAK,OAAO,SAAS,OAAO,MAAM,OAAO,OAAO,CAAC;CACjD,KAAK,OAAO,SAAS,OAAO,MAAM;CAClC,MAAM,OAAO,SAAS,OAAO,MAAM;AACrC,CAAC;;AAID,MAAM,YAAY,OAAO,MAAM,CAC7B,OAAO,OAAO,EAAE,QAAQ,OAAO,MAAM,MAAM,EAAE,CAAC,GAC9C,OAAO,MAAM,MAAM,CACrB,CAAC;AAGD,MAAM,kBAAkB,OAAO,oBAAoB,OAAO,eAAe,SAAS,CAAC;AAEnF,MAAM,aAAa,SACjB,YAAY,OAAO,KAAK,SAAS;;AAGnC,MAAM,iBAAiB;AAEvB,MAAM,aAAa,MAAiB,QAClC,KACE,UAAU,IAAI,GACdA,MAAI,WAAW,WAAW,OAAO,SAAS,cAAc,GACxD,OAAO,KACJ,WACC,IAAI,QAAQ,gBAAgB;CAC1B,UAAA;CACA,GAAI,OAAO,QAAQ,KAAA,KAAa,EAAE,QAAQ,OAAO,IAAI;CACrD;AACF,CAAC,CACL,CACF;AAEF,MAAM,eAAe,QAAgB,SACnC,MAAM,MAAM,MAAM,CAAC,CAAC,KAClB,MAAM,KACJ,WACuB,IAAI,QAAQ,YAAY;CAAE,UAAA;CAAoB,KAAK;AAAK,CAAC,CAClF,GACA,MAAM,OACJ,KACA,WACuB,IAAI,QAAQ,QAAQ;CAAE,UAAA;CAAoB,KAAK;AAAK,CAAC,CAC9E,GACA,MAAM,KACJ,WAEE,IAAI,QAAQ,WAAW;CAAE,UAAA;CAAoB,SAAS;CAAQ,KAAK;AAAK,CAAC,CAC7E,GACA,MAAM,KACJ,WAEE,IAAI,QAAQ,WAAW;CAAE,UAAA;CAAoB,SAAS;CAAc,KAAK;AAAK,CAAC,CACnF,GACA,MAAM,KACJ,WAEE,IAAI,QAAQ,WAAW;CAAE,UAAA;CAAoB,SAAS;CAAW,KAAK;AAAK,CAAC,CAChF,GACA,MAAM,KACJ,WACuB,IAAI,QAAQ,sBAAsB;CAAE,UAAA;CAAoB,KAAK;AAAK,CAAC,CAC5F,GACA,MAAM,MACH,MAAM,KAAK,MACX,MAAuB,IAAI,QAAQ,YAAY;CAAE,UAAA;CAAoB,QAAQ;CAAG,KAAK;AAAK,CAAC,CAC9F,GACA,MAAM,aACmB,IAAI,QAAQ,eAAe;CAAE,UAAA;CAAoB,KAAK;AAAK,CAAC,CACrF,CACF;;AAGF,MAAa,aAAa,QAAgB,SACxC,gBAAgB,IAAI,CAAC,CAAC,KACpB,OAAO,KAAK,SAAS,OAAO,UAAU,UAAU,MAAM,IAAI,SAAS,YAAY,QAAQ,IAAI,CAAC,CAAC,GAC7F,OAAO,oBAAoB,YAAY,QAAQ,IAAI,CAAC,CACtD;;AAYF,MAAM,cAAc;;;;;AAMpB,MAAa,qBAAqB,SAChC,gBAAgB,IAAI,CAAC,CAAC,KACpB,OAAO,KAAK,SACV,KACE,UAAU,IAAI,GACdA,MAAI,QAAQ,WAAW,OAAO,SAAS,SAAS,GAChDA,MAAI,KAAK,WAAW,OAAO,MAAM,EAAE,GACnCA,MAAI,WAAW,SAAyB,OAAO,SAAS,YAAY,YAAY,KAAK,IAAI,CAAC,CAC5F,CACF,GACA,OAAO,oBAAoB,OAAO,KAAa,CAAC,CAClD"}

package/dist/index.d.mts

@@ -0,0 +1,4 @@
+import { FalImageEditModel, FalImageModel } from "./models.mjs";
+import { t as FalImageGenerator_d_exports } from "./FalImageGenerator.mjs";
+import { t as codec_d_exports } from "./codec.mjs";
+export { FalImageEditModel, FalImageGenerator_d_exports as FalImageGenerator, FalImageModel, codec_d_exports as codec };

package/dist/index.mjs

@@ -0,0 +1,4 @@
+import { t as codec_exports } from "./codec.mjs";
+import { t as FalImageGenerator_exports } from "./FalImageGenerator.mjs";
+import "./models.mjs";
+export { FalImageGenerator_exports as FalImageGenerator, codec_exports as codec };

package/dist/models.d.mts

@@ -0,0 +1,32 @@
+//#region src/models.d.ts
+/**
+ * fal endpoint identifiers (as of September 2026). Unlike every other
+ * provider here, the "model" is a *path*: it selects the endpoint, and
+ * text-to-image and edit are separate endpoints of the same model
+ * family. Pass a `FalImageModel` to `generate` and a `FalImageEditModel`
+ * to `edit`.
+ *
+ * The `(string & {})` tail keeps autocomplete on the literals while
+ * accepting any string, so fal's whole catalogue works without an SDK
+ * update: the id is the model page's URL after `fal.ai/models/`.
+ *
+ * Read that literally. Whether an id carries the `fal-ai/` prefix varies
+ * even between generations of one model (`fal-ai/bytedance/seedream/v4.5/edit`
+ * has it, `bytedance/seedream/v5/pro/text-to-image` does not), and a
+ * wrong guess is fal's "Application not found", not a 404 you can read.
+ *
+ * Reference: https://fal.ai/models
+ */
+type FalImageModel = "fal-ai/flux-2-pro" | "fal-ai/flux/schnell" | "fal-ai/flux/dev" | "bytedance/seedream/v5/pro/text-to-image" | "alibaba/qwen-image-3/text-to-image" | "meta/muse-image/text-to-image" | "openai/gpt-image-2" | "fal-ai/nano-banana-2" | (string & {});
+/**
+ * Edit endpoints. A generate id sent to `edit` gets fal's 422 for an
+ * unknown field.
+ *
+ * Which wire field the references ride in differs per endpoint and the
+ * adapter works that out on its own, so any edit endpoint fal hosts
+ * works here, single-image ones included.
+ */
+type FalImageEditModel = "fal-ai/flux-2-pro/edit" | "bytedance/seedream/v5/pro/edit" | "fal-ai/bytedance/seedream/v4.5/edit" | "alibaba/qwen-image-3/edit" | "fal-ai/nano-banana-2/edit" | "openai/gpt-image-2/edit" | "fal-ai/qwen-image-edit" | "fal-ai/flux/dev/image-to-image" | (string & {});
+//#endregion
+export { FalImageEditModel, FalImageModel };
+//# sourceMappingURL=models.d.mts.map

package/dist/models.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.mts","names":[],"sources":["../src/models.ts"],"mappings":";;;;;;;;;;;;;;;;;;;KAkBY;;;;;;;;;KAoBA"}

package/dist/models.mjs

@@ -0,0 +1 @@
+export {};

package/dist/rolldown-runtime-D7D4PA-g.mjs

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll as t };

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@effect-uai/fal",
+  "version": "0.13.0",
+  "description": "fal provider for @effect-uai/core.",
+  "keywords": [
+    "ai",
+    "effect",
+    "fal",
+    "flux",
+    "image-generation",
+    "seedream"
+  ],
+  "homepage": "https://github.com/betalyra/effect-uai/tree/main/packages/providers/fal",
+  "bugs": {
+    "url": "https://github.com/betalyra/effect-uai/issues"
+  },
+  "license": "MIT",
+  "author": "Betalyra",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/betalyra/effect-uai",
+    "directory": "packages/providers/fal"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./FalImageGenerator": {
+      "types": "./dist/FalImageGenerator.d.mts",
+      "import": "./dist/FalImageGenerator.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "effect": "4.0.0-rc.111",
+    "typescript": "^7.0.2",
+    "@effect-uai/core": "0.13.0"
+  },
+  "peerDependencies": {
+    "@effect-uai/core": ">=0.14.0 <1",
+    "effect": ">=4.0.0-rc.111 <5.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}