@sheetxl/sdk 0.8.0-beta.14 → 0.8.0-beta.16

package/types/src/license/LicenseDetails.d.ts

@@ -24,5 +24,32 @@ export interface LicenseDetails {
     getKeyFrom(): string;
     getBuildVersion(): string;
     getBuildDate(): string;
+    /**
+     * When this build's evaluation period ends — from then on, unlicensed, it refuses exports — or
+     * `null` for an unstamped build.
+     */
+    getEvalPeriodEnd(): Date | null;
+    /**
+     * When this build's grace ends — from then on, unlicensed, it stops calculating and running
+     * scripts — or `null` for an unstamped build.
+     */
+    getEvalStopDate(): Date | null;
+    /**
+     * The license as one report row — what `info` and `sheetxl info` print. `includeHost` adds where
+     * the key came from and its capacity, for a human diagnosing a machine.
+     */
+    getSummary(includeHost?: boolean): LicenseSummary;
+}
+/**
+ * @hidden
+ *
+ * A license as one report row: how it stands, the edition, what qualifies it, and the exact command
+ * that resolves a `warn`.
+ */
+export interface LicenseSummary {
+    level: 'ok' | 'warn';
+    value: string;
+    detail?: string;
+    fix?: string;
 }
 //# sourceMappingURL=LicenseDetails.d.ts.map

package/types/src/license/LicenseManager.d.ts

@@ -1,3 +1,4 @@
+import { EvalState } from './_Utils';
 import { LicenseDetails } from './LicenseDetails';
 declare class LM {
     constructor();
@@ -26,16 +27,32 @@ declare class LM {
      */
     getDetails(): Promise<LicenseDetails>;
     /**
-     * Return the current license details, after confirming this runtime may run under them.
+     * Return the current license details, after confirming this runtime may use `meter` under them.
+     *
+     * @param meter What is about to be used: `'calcs'`, `'exports'` (a write in any format but
+     * `.sxl`) or `'scripts'`. Omitted, it asks whether this runtime may run at all.
+     * @param count How much of it — what a metered license will count against its limit.
      *
      * @remarks
-     * {@link getDetails} only reports. This also enforces: in a browser it always resolves, because
-     * an unlicensed page runs with the evaluation watermark. Outside a browser an evaluation runs
-     * for a limited period from the build's date; past it a valid license key is required, and this
-     * rejects with the reason and what to do. The engine calls it when it starts, so a host that
-     * wants to fail at startup instead of at the first workbook calls it itself.
+     * {@link getDetails} only reports. This also enforces: on a web page it always resolves, because
+     * an unlicensed page runs with the evaluation watermark. Anywhere else an unlicensed build runs
+     * for an evaluation period from its build date; after it `'exports'` are refused, and after its
+     * grace everything metered is. The rejection carries the reason and what to do. Opening a
+     * workbook and saving it as `.sxl` are never refused. The engine calls this when it starts, so a
+     * host that wants to fail at startup instead of at the first workbook calls it itself.
+     */
+    assertUsable(meter?: string, count?: number): Promise<LicenseDetails>;
+    /**
+     * Where this runtime stands under its license: `licensed`, in its `evaluation`, in the `grace`
+     * that refuses exports, or `stopped` (no calculation, scripts or exports).
+     */
+    getEvalState(): Promise<EvalState>;
+    /**
+     * Whether this runtime runs under the evaluation watermark: an unlicensed web page off localhost.
+     * An xlsx exported from it carries the watermark as a sheet added before the workbook's own.
      */
-    assertUsable(): Promise<LicenseDetails>;
+    isWatermarked(): Promise<boolean>;
+    private _enforce;
     /**
      * Return the license key in use, or `null` for an evaluation.
      *

package/types/src/license/_Utils.d.ts

@@ -18,14 +18,45 @@ export declare function getBuildDate(): string;
  * unlicensed.
  */
 export declare const EVAL_PERIOD_DAYS = 70;
+/**
+ * How long an unlicensed build keeps running after its evaluation period, in days.
+ *
+ * @remarks
+ * The grace is the second step, not a second period: the build still loads and calculates, but
+ * refuses every export (any format but `.sxl`), so the pressure lands on the deliverable without
+ * ever altering a user's file. Once it is over, calculation and scripts stop too. Opening and
+ * saving `.sxl` is never refused.
+ */
+export declare const EVAL_GRACE_DAYS = 30;
 /** When this build's evaluation period ends, or `null` for an unstamped (workspace, test) build. */
 export declare function getEvalPeriodEnd(): Date | null;
+/** When this build stops running unlicensed — the end of its grace — or `null` when unstamped. */
+export declare function getEvalStopDate(): Date | null;
 /** Whether this build's evaluation period is over. An unstamped build never expires. */
 export declare function isEvalPeriodExpired(): boolean;
+/** Whether this build's grace is over too. An unstamped build never stops. */
+export declare function isEvalStopped(): boolean;
+/**
+ * Where a process stands under its license, as enforcement sees it.
+ *
+ * - `licensed` — a key covers it; nothing below applies.
+ * - `evaluation` — unlicensed, inside the evaluation period: runs in full. A page served over
+ *   http(s) stays here for good — the watermark is its enforcement.
+ * - `grace` — past the period: exports (every format but `.sxl`) are refused.
+ * - `stopped` — past the grace too: calculation and scripts stop as well. A workbook still opens
+ *   and still saves as `.sxl`, so no one is locked out of their own work.
+ */
+export type EvalState = 'licensed' | 'evaluation' | 'grace' | 'stopped';
+/** The unlicensed state this build is in by its date alone. */
+export declare function getEvalPeriodState(): Exclude<EvalState, 'licensed'>;
+/** The formats that are never refused or metered: SheetXL's own (`.sxl`, and its plain JSON form). */
+export declare function isFreeFormat(formatKey: string): boolean;
+/** What a refusal says: the key's own problems, then the period, then where to go. */
+export declare function evalRefusalMessage(exceptions: readonly string[]): string;
 /**
- * The exception an expired evaluation carries. It names the date and the two ways out, because
- * every surface that lists exceptions (the banner, `sheetxl info`, the MCP handshake) shows it
- * verbatim and none of them knows more than the text.
+ * The exception an expired evaluation carries — in its grace, or stopped. It names the dates and
+ * the two ways out, because every surface that lists exceptions (the banner, `sheetxl info`, the
+ * MCP handshake) shows it verbatim and none of them knows more than the text.
  */
 export declare function evalPeriodExpiredMessage(): string;
 /**

package/types/src/license/index.d.ts

@@ -1,3 +1,4 @@
 export * from './LicenseManager';
 export * from './LicenseDetails';
+export type { EvalState } from './_Utils';
 //# sourceMappingURL=index.d.ts.map

package/types/src/license/runtime.browser.d.ts

@@ -1,3 +1,4 @@
+import { EvalState } from './_Utils';
 import { HostDetails, LicenseKeySource } from './Types';
 import { LicenseDetails } from './LicenseDetails';
 /**
@@ -7,6 +8,19 @@ import { LicenseDetails } from './LicenseDetails';
  * host, and are checked like production. Outside a window (a worker, node under test) both are `null`.
  */
 export declare function getHostDetails(): Promise<HostDetails>;
+/**
+ * Whether this page is on the web — served over http(s) — and so takes the `browser` license:
+ * origin-checked keys, and the evaluation watermark as its enforcement.
+ *
+ * @remarks
+ * Any other scheme is a page inside an application rather than a site: the VS Code webview
+ * (`vscode-webview:`), Electron (`app:`, `file:`), Tauri. Those take the terms a Node process
+ * does — no watermark, the evaluation period, then its grace — so the line is the host, not the
+ * product, and nothing has to declare it. Plain `http:` is web too: an intranet site is still a
+ * site, and the cheapest bypass there could be is "serve it over http". Outside a window (a worker
+ * without a location, node under test) there is no page to classify, and it stays web.
+ */
+export declare function isWebPage(): Promise<boolean>;
 /**
  * Only the loopback host over http(s) is a dev environment. A dev *build* served on any other host
  * (a LAN IP, a tunnel) — or under any other scheme — is checked exactly like production: license
@@ -19,17 +33,31 @@ export declare function isDevEnv(): Promise<boolean>;
  */
 export declare function readLicenseKey(): Promise<LicenseKeySource>;
 /**
- * A page always runs: an unlicensed one runs with the evaluation watermark, which is the browser's
- * enforcement. Never throws.
+ * Where this page stands under `details` (see {@link EvalState}).
+ *
+ * @remarks
+ * A web page is never past its evaluation: an unlicensed one runs with the watermark, which is the
+ * browser's enforcement. An application page ({@link isWebPage}) is enforced as Node is, with a
+ * key that covers it — valid, with nothing it fails — as its license.
+ */
+export declare function getEvalState(details: LicenseDetails): Promise<EvalState>;
+/**
+ * Whether this page runs under the evaluation watermark — an unlicensed web page off localhost. An
+ * export from it carries the watermark too, as a sheet of its own.
  */
-export declare function assertUsable(_details: LicenseDetails): void;
+export declare function isWatermarked(details: LicenseDetails): Promise<boolean>;
 /**
- * An evaluation: unrestricted on localhost, and with the evaluation watermark anywhere else.
+ * An evaluation: unrestricted on localhost, and with the evaluation watermark anywhere else on the
+ * web.
  */
 export declare function getEvalLicense(keyFrom: string): Promise<LicenseDetails>;
 /**
  * The license for this page when the host set no key: the key file's, an evaluation when there is
  * none, or `unavailable` when it could not be loaded.
+ *
+ * @remarks
+ * The key file is a web deployment's convention. An application page that has none, or cannot
+ * reach one, is a plain evaluation — its host passes a key to `setLicenseKey` when it has one.
  */
 export declare function getLicense(): Promise<LicenseDetails>;
 export declare function setKey(key: string, force?: boolean): Promise<void>;

package/types/src/license/runtime.node.d.ts

@@ -1,3 +1,4 @@
+import { EvalState } from './_Utils';
 import { HostDetails, LicenseKeySource } from './Types';
 import { LicenseDetails } from './LicenseDetails';
 export declare function getHostDetails(): Promise<HostDetails>;
@@ -12,16 +13,18 @@ export declare function getEvalLicense(keyFrom: string): Promise<LicenseDetails>
  * or an evaluation.
  */
 export declare function getLicense(): Promise<LicenseDetails>;
+/** Outside a browser nothing is watermarked: the evaluation period is the enforcement. */
+export declare function isWatermarked(_details: LicenseDetails): Promise<boolean>;
 /**
- * Whether this process may run under `details`; throws with the reason when it may not.
+ * Where this process stands under `details` (see {@link EvalState}).
  *
  * @remarks
  * Outside a browser there is no watermark to fall back on, so the evaluation period is the
- * enforcement: once it is over, only a current license key that covers a server runs. A key's
- * capacity exceptions (an oversize host) are still reported rather than enforced, exactly as before
- * the period ended. An unstamped build has no period and always runs.
+ * enforcement: once it is over, only a current license key that covers a server is `licensed`. A
+ * key's capacity exceptions (an oversize host) are reported rather than enforced. An unstamped
+ * build has no period and is never past it.
  */
-export declare function assertUsable(details: LicenseDetails): void;
+export declare function getEvalState(details: LicenseDetails): Promise<EvalState>;
 export declare function setKey(key: string, force?: boolean): Promise<void>;
 export declare function getKey(): Promise<string | undefined>;
 export declare function printBanner(isUser: boolean): Promise<void>;

package/types/src/license/summary.d.ts

@@ -0,0 +1,18 @@
+import { LicenseDetails, LicenseSummary } from './LicenseDetails';
+/**
+ * The license as one report row, agent-first: the edition, plus anything ACTIONABLE — an
+ * exception, an expiry inside 30 days, or an evaluation's dates. Entitlement capacity (cores/GB)
+ * and where the key came from are host diagnostics, not operational facts, so they ride only under
+ * `includeHost` — an agent cannot act on `32 cores`, but a human debugging "why is this machine
+ * licensed differently" can act on `envVar` vs `configStore`.
+ *
+ * @remarks
+ * Here rather than in the report that prints it (`info`, `sheetxl info`): what a license means is
+ * the license's business, and the report only lays the row out.
+ *
+ * Exceptions surface as a warning rather than an error — an evaluation or unlicensed engine still
+ * opens and saves, and failing a handshake over it would strand an agent that could have done the
+ * work.
+ */
+export declare function summarizeLicense(details: LicenseDetails, includeHost?: boolean): LicenseSummary;
+//# sourceMappingURL=summary.d.ts.map