@farm.js/scripts 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Farm.js Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,55 @@
+# `@farm.js/scripts`
+
+Typed, lifecycle-aware third-party browser scripts for Farm.js.
+
+Use this plugin when a browser SDK arrives through an external `<script>` and exposes a global.
+Farm owns when that script loads, deduplicates concurrent requests, waits for readiness, and gives
+application code a typed handle instead of an ambient `window.vendor` access.
+
+```bash
+pnpm add @farm.js/scripts
+```
+
+```ts
+// src/lib/scripts.ts
+import { defineScript } from "@farm.js/scripts/client";
+
+interface SupportChatSDK {
+  load(options: { userId: string }): void;
+  open(): void;
+}
+
+export const supportChat = defineScript<SupportChatSDK>({
+  name: "support-chat",
+  src: "https://cdn.example.com/chat.js",
+  global: "SupportChat",
+  load: "manual",
+  preconnect: true,
+});
+```
+
+```ts
+// farm.config.ts
+import { defineConfig } from "@farm.js/core";
+import { scripts } from "@farm.js/scripts";
+import { supportChat } from "./src/lib/scripts";
+
+export default defineConfig({
+  plugins: [scripts({ scripts: [supportChat] })],
+});
+```
+
+```ts
+await supportChat.use((sdk) => {
+  sdk.load({ userId: "user_123" });
+  sdk.open();
+});
+```
+
+Built-in load strategies are `immediate`, `after-hydration`, `idle`, `interaction`, `manual`, and
+element visibility. Definitions can also declare consent categories, dependency order, retries,
+timeouts, preconnect hints, module scripts, SRI, CORS, referrer policy, fetch priority, and vendor
+`data-*` attributes.
+
+See the [Farm Scripts documentation](https://farmjs.dev/docs/plugins/scripts) for all options,
+recipes, consent behavior, and limits.

package/dist/client.d.ts

@@ -0,0 +1,43 @@
+import type { ResolvedScriptDefinition, ScriptConsentState, ScriptDefinition, ScriptHandle, ScriptRuntime } from "./types.js";
+export type { AnyScriptHandle, ResolvedScriptDefinition, ScriptConsentState, ScriptDefinition, ScriptDuration, ScriptHandle, ScriptLoadStrategy, ScriptSnapshot, ScriptStatus, ScriptStatusListener, } from "./types.js";
+export declare class ScriptEnvironmentError extends Error {
+    name: string;
+}
+export declare class ScriptNotRegisteredError extends Error {
+    name: string;
+}
+export declare class ScriptConsentRequiredError extends Error {
+    readonly scriptName: string;
+    readonly category: string;
+    name: string;
+    constructor(scriptName: string, category: string);
+}
+export declare class ScriptLoadError extends Error {
+    readonly scriptName: string;
+    readonly src: string;
+    name: string;
+    constructor(scriptName: string, src: string);
+}
+export declare class ScriptTimeoutError extends Error {
+    readonly scriptName: string;
+    readonly timeoutMs: number;
+    name: string;
+    constructor(scriptName: string, timeoutMs: number);
+}
+export declare class ScriptGlobalMissingError extends Error {
+    readonly scriptName: string;
+    readonly globalPath: string;
+    name: string;
+    constructor(scriptName: string, globalPath: string);
+}
+/** Define one typed external browser script. Register the returned handle with `scripts()`. */
+export declare function defineScript<T = void>(definition: ScriptDefinition): ScriptHandle<T>;
+/** Set an application-owned consent category. Consent is intentionally not persisted by Farm. */
+export declare function setScriptConsent(category: string, state: ScriptConsentState): void;
+export declare function grantScriptConsent(category: string): void;
+export declare function denyScriptConsent(category: string): void;
+export declare function clearScriptConsent(category: string): void;
+export declare function getScriptConsent(category: string): ScriptConsentState;
+/** @internal Start the browser lifecycle for definitions serialized by the Farm plugin. */
+export declare function startScriptRuntime(definitions: readonly ResolvedScriptDefinition[], runtimeWindow?: Window & typeof globalThis, basePath?: string): ScriptRuntime;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,wBAAwB,EACxB,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,EACZ,aAAa,EAId,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,eAAe,EACf,wBAAwB,EACxB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,cAAc,EACd,YAAY,EACZ,oBAAoB,GACrB,MAAM,YAAY,CAAC;AAyBpB,qBAAa,sBAAuB,SAAQ,KAAK;IACtC,IAAI,SAA4B;CAC1C;AAED,qBAAa,wBAAyB,SAAQ,KAAK;IACxC,IAAI,SAA8B;CAC5C;AAED,qBAAa,0BAA2B,SAAQ,KAAK;IAGjD,QAAQ,CAAC,UAAU,EAAE,MAAM;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM;IAHlB,IAAI,SAAgC;gBAElC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM;CAM5B;AAED,qBAAa,eAAgB,SAAQ,KAAK;IAGtC,QAAQ,CAAC,UAAU,EAAE,MAAM;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM;IAHb,IAAI,SAAqB;gBAEvB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,MAAM;CAIvB;AAED,qBAAa,kBAAmB,SAAQ,KAAK;IAGzC,QAAQ,CAAC,UAAU,EAAE,MAAM;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM;IAHnB,IAAI,SAAwB;gBAE1B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM;CAI7B;AAED,qBAAa,wBAAyB,SAAQ,KAAK;IAG/C,QAAQ,CAAC,UAAU,EAAE,MAAM;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM;IAHpB,IAAI,SAA8B;gBAEhC,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM;CAM9B;AAED,+FAA+F;AAC/F,wBAAgB,YAAY,CAAC,CAAC,GAAG,IAAI,EAAE,UAAU,EAAE,gBAAgB,GAAG,YAAY,CAAC,CAAC,CAAC,CA0CpF;AAED,iGAAiG;AACjG,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB,GAAG,IAAI,CA6BlF;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAExD;AAED,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,kBAAkB,CAKrE;AAED,2FAA2F;AAC3F,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,SAAS,wBAAwB,EAAE,EAChD,aAAa,GAAE,MAAM,GAAG,OAAO,UAAmB,EAClD,QAAQ,SAAM,GACb,aAAa,CA8Lf"}