@progress/sitefinity-webservices-sdk 1.1.16 → 2.0.0

package/{dist/src → src}/constants.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Operator names used by the fluent query-expression API.
+ *
+ * Most consumers should use {@link Query} and {@link WhereQuery} instead of constructing
+ * expressions from these values directly.
+ */
 export declare const EXPRESSION_TYPE: {
     query: number;
     where: number;
@@ -16,6 +22,9 @@ export declare const EXPRESSION_TYPE: {
     startsWith: string;
     endsWith: string;
 };
+/**
+ * OData query parameter names emitted by {@link QueryBuilder}.
+ */
 export declare const ODATA_PARAMS: {
     $filter: string;
     $select: string;
@@ -26,6 +35,9 @@ export declare const ODATA_PARAMS: {
     $count: string;
     $search: string;
 };
+/**
+ * Sitefinity-specific query parameter names supported by SDK requests.
+ */
 export declare const SF_PARAMS: {
     provider: string;
     culture: string;
@@ -33,6 +45,9 @@ export declare const SF_PARAMS: {
     fallbackParams: string;
     parentId: string;
 };
+/**
+ * Standard and Sitefinity-specific HTTP header names used by SDK requests.
+ */
 export declare const HEADER_NAMES: {
     contentType: string;
     authorization: string;
@@ -49,6 +64,9 @@ export declare const HEADER_NAMES: {
     chunkedFileUploadSessionId: string;
     blobStorageProviderName: string;
 };
+/**
+ * HTTP method names used by the request classes.
+ */
 export declare const HTTP_METHODS: {
     get: string;
     put: string;
@@ -56,6 +74,9 @@ export declare const HTTP_METHODS: {
     patch: string;
     delete: string;
 };
+/**
+ * Content types emitted by SDK requests.
+ */
 export declare const CONTENT_TYPES: {
     json: string;
 };

package/src/utils.d.ts

@@ -0,0 +1,103 @@
+/**
+ * General-purpose value, URL, serialization, and response conversion helpers used by the SDK.
+ *
+ * These helpers are exported for backward compatibility. Application code should normally use
+ * the higher-level {@link Sitefinity}, {@link Data}, and {@link Query} APIs.
+ */
+export declare class utils {
+    /**
+     * Determines whether a value is a primitive or boxed string.
+     *
+     * @param obj Value to inspect.
+     * @returns `true` when the value is a string.
+     */
+    static isString(obj: any): boolean;
+    /**
+     * Determines whether a value is a boolean.
+     *
+     * @param obj Value to inspect.
+     * @returns `true` for primitive boolean values.
+     */
+    static isBoolean(obj: any): boolean;
+    /**
+     * Determines whether a value is a {@link Blob}.
+     *
+     * @param obj Value to inspect.
+     * @returns `true` when the value is a `Blob`.
+     */
+    static isBlob(obj: any): boolean;
+    /**
+     * Determines whether a value is a finite number.
+     *
+     * @param value Value to inspect.
+     * @returns `true` for finite numeric values.
+     */
+    static isNumber(value: any): boolean;
+    /**
+     * Determines whether a value is callable.
+     *
+     * @param func Value to inspect.
+     * @returns `true` when the value is a function.
+     */
+    static isFunction(func: any): boolean;
+    /**
+     * Converts request data to its wire representation.
+     *
+     * Strings and blobs are returned unchanged. Other values are serialized with `JSON.stringify`.
+     *
+     * @param data Request body value.
+     * @returns The original string or blob, or a JSON string for other values.
+     */
+    static serializeToJSON(data: any): string;
+    /**
+     * Parses a response string as a number or JSON value.
+     *
+     * ISO 8601 date strings in parsed objects and arrays are converted to {@link Date} instances.
+     * Non-JSON text returns `null`.
+     *
+     * @param data Response text to parse.
+     * @returns The parsed value, or `null` when the input is empty or not valid JSON.
+     */
+    static parseStringToJson(data: any): any;
+    /**
+     * Converts top-level {@link Date} properties to ISO 8601 strings in place.
+     *
+     * @param data Object that will be sent in a request.
+     * @returns The same object instance after conversion.
+     */
+    static convertDateFieldToISOString(data: object): object;
+    /**
+     * Generates a four-character hexadecimal segment.
+     *
+     * @returns A pseudo-random lowercase hexadecimal string.
+     */
+    static hex16(): string;
+    /**
+     * Ensures that a URL ends with exactly one slash.
+     *
+     * @param url URL to normalize.
+     * @returns The normalized URL.
+     */
+    static addTrailingSlash(url: string): string;
+    /**
+     * Removes one trailing slash from a URL.
+     *
+     * @param url URL to normalize.
+     * @returns The URL without a trailing slash.
+     */
+    static removeSlashes(url: string): string;
+    /**
+     * Performs the SDK's backward-compatible shallow clone operation.
+     *
+     * The optional action is called while properties are copied and is used by fluent query
+     * objects to update the cloned instance.
+     *
+     * @param from Source object.
+     * @param to Optional target object.
+     * @param action Optional callback invoked with the target during copying.
+     * @returns The populated target object.
+     */
+    static clone(from: any, to?: {}, action?: Function): any;
+    private static _parseDateProperties;
+    private static _tryFormatFieldToDate;
+}

package/.editorconfig

@@ -1,29 +0,0 @@
-# Manage common editor configurations
-# set for example indentation tab and space
-# VS Extension: https://visualstudiogallery.msdn.microsoft.com/c8bccfe2-650c-4b42-bc5c-845e21f96328
-# more extensions and plugins for your favorite editor here: http://editorconfig.org/#download
-
-; Top-most EditorConfig file
-root = true
-
-; 4-column space indentation
-[*]
-indent_size = 4
-indent_style = space
-insert_final_newline = true
-trim_trailing_whitespace = true
-
-[*.md]
-indent_size = 4
-indent_style = space
-trim_trailing_whitespace = false
-
-[*.json]
-indent_size = 2
-indent_style = space
-trim_trailing_whitespace = false
-
-[*.min.*]
-indent_style = ignore
-trim_trailing_whitespace = false
-insert_final_newline = ignore

package/.eslintignore

@@ -1,4 +0,0 @@
-node_modules
-dist
-config
-coverage

package/.eslintrc.js

@@ -1,40 +0,0 @@
-module.exports = {
-    "env": {
-        "browser": true,
-        "es2021": true
-    },
-    "extends": [
-        "eslint:recommended",
-        "plugin:@typescript-eslint/recommended"
-    ],
-    "overrides": [
-    ],
-    "parser": "@typescript-eslint/parser",
-    "parserOptions": {
-        "ecmaVersion": "latest",
-        "sourceType": "module"
-    },
-    "plugins": [
-        "@typescript-eslint"
-    ],
-    "rules": {
-        "indent": [
-            "error",
-            4
-        ],
-        "quotes": [
-            "error",
-            "double"
-        ],
-        "semi": [
-            "error",
-            "always"
-        ],
-        "@typescript-eslint/no-explicit-any": "off",
-        "@typescript-eslint/ban-types": "off",
-        "no-useless-escape": "off",
-        "no-prototype-builtins": "off",
-        "@typescript-eslint/no-empty-function": "off",
-        "no-constant-condition": "off"
-    }
-};

package/.github/copilot-instructions.md

@@ -1,72 +0,0 @@
-# sitefinity-webservices-sdk — TypeScript SDK
-
-## Shared Conventions (Sitefinity DX Monorepo)
-
-This project is part of the Sitefinity DX monorepo (6 independent projects: `admin-app`, `nextjs-renderer`, `netcore-renderer`, `sitefinity-webservices-sdk`, `sitefinity-widget-designers`, `e2e-tests`). The rules below apply to all projects; project-specific rules follow.
-
-### Formatting
-- **4-space** indent for source; **2-space** for YAML.
-- Trim trailing whitespace (except `.md` and `.min.*`); final newline on every file.
-- Max line width: **120 chars**.
-
-### Naming
-- Files: `kebab-case` (TS/JS). C# filenames: `PascalCase` matching class.
-- Classes / interfaces / types / enums: `PascalCase`.
-- Variables, functions, methods: `camelCase`.
-- Constants: `UPPER_SNAKE_CASE`.
-- C# private fields: `_camelCase`.
-
-### TypeScript
-- Prefer `strict: true` patterns in new code. Avoid `any` — use generics or `unknown`.
-- `const` by default; `let` only when reassigning; never `var`.
-- `interface` for object shapes; `type` for unions, intersections, mapped types.
-- Use `?.` and `??` over manual null checks.
-- Prefer named exports over default exports, unless the framework requires default (Next.js pages/layouts).
-
-### Imports
-- Use configured path aliases (`@progress/sitefinity-*`) where available; follow the project's existing style when aliases aren't configured.
-- Order: (1) framework/library, (2) project/alias, (3) relative. Blank line between groups.
-- Don't import whole modules when only specific members are needed.
-
-### Error Handling
-- Never silently swallow exceptions — at minimum, log.
-- Use typed errors / specific error classes where applicable.
-- Never leave floating promises.
-
-### Avoiding Duplication (critical)
-- **Before creating a new utility, helper, or shared function**, search the current project AND sibling projects for equivalents.
-- **Before adding a dependency**, check if an existing one already provides the functionality.
-- Follow existing patterns (base classes, services, decorators) rather than inventing alternatives.
-- Don't create parallel abstractions. Extend or reuse; only introduce a new shared abstraction when there is a clear owner and reuse path.
-
-### Cross-Project Ownership
-Where shared logic belongs:
-- **SDK / client-side data access** → `sitefinity-webservices-sdk`
-- **Widget metadata / property decorators** → `sitefinity-widget-designers`
-- **Angular UI / admin features** → `admin-app`
-- **Next.js rendering / SSR** → `nextjs-renderer`
-- **Server-side rendering (.NET)** → `netcore-renderer`
-- **Shared test helpers / fixtures** → `e2e-tests`
-
-Don't duplicate logic across projects — put it in the owner.
-
-### Testing
-- Co-locate unit tests with source using the project's test-suffix convention, unless the project section says otherwise. Cypress e2e tests are organized by feature under `e2e/`, not co-located.
-- Tests must be deterministic — no external services, network, or timing (exception: Cypress e2e against hosted envs).
-- Arrange/act/assert structure; descriptive names; mock external dependencies.
-
-### Generated / Build Output
-- Never edit: `dist/`, `lib/`, `.next/`, `node_modules/`, `bin/`, `obj/`, auto-generated docs.
-- Don't commit build artifacts.
-
-### Documentation
-- JSDoc / XML doc for **public APIs only**.
-- No trivial comments. For complex logic, comment **why**, not **what**.
-
-### Git
-- Imperative-mood commit messages ("Add widget registry", not "Added…").
-- One logical change per commit.
-
----
-
-Project-specific rules: see [`instructions/sitefinity-webservices-sdk.instructions.md`](instructions/sitefinity-webservices-sdk.instructions.md).

package/.github/instructions/sitefinity-webservices-sdk.instructions.md

@@ -1,53 +0,0 @@
----
-applyTo: "**"
----
-<!-- The two `<service>.instructions.md` files (repo-root and per-service) share the SAME body; only the `applyTo` frontmatter differs. Keep them in sync manually. -->
-
-# sitefinity-webservices-sdk — TypeScript SDK
-
-## Tech Stack
-- **Language**: TypeScript (vanilla — no framework)
-- **Target**: ES5 for broad browser compatibility
-- **Build**: Webpack 5 (separate dev and prod configs in `config/webpack.*.ts` — TypeScript-authored)
-- **Output**: UMD library bundle (global `Sitefinity` in browser, CommonJS in Node)
-- **Testing**: Karma + Jasmine (browser-based) with `jasmine-ajax` for HTTP mocking
-
-## Conventions
-
-- **Quote style**: Double quotes (`"`).
-- **Semicolons**: Always required.
-- **Indentation**: 4 spaces for code, **2 spaces for JSON** (project-specific override).
-- **HTTP implementation**: Uses `XMLHttpRequest` (NOT Fetch or Axios). Check `readyState === 4` before processing. 200–206 = success, 400+ = error.
-- **Callback pattern**: The SDK uses callbacks (`successCb`, `failureCb`, `progressCb`), NOT Promises. Follow this for new API methods.
-- **API design**: Fluent/chainable API (see `src/Sitefinity.ts`):
-  ```typescript
-  sdk.data(options).get({ query, successCb, failureCb });
-
-  // Batch: methods mutate internal state and return void, not the batch for further chaining
-  const batch = sdk.batch(success, failure, progress, options);
-  batch.get({...});
-  batch.create({...});
-  // Transactional grouping for atomic data modifications:
-  const tx = batch.beginTransaction();
-  tx.create({...});
-  batch.endTransaction(tx);
-  batch.execute();
-  ```
-- **Data class methods**: `.get()`, `.getSingle()`, `.create()`, `.update()`, `.destroy()`, `.operation()`, `.getProperty()`, `.getOperations()`, and `.chunkUpload` (file upload service).
-- **Request hierarchy**: `RequestBase` → `ExecutableRequest` (HTTP execution) → specific request types (`GetRequest`, `CreateRequest`, `UpdateRequest`, `DeleteRequest`). New request types must extend this hierarchy.
-- **Query builder**: Fluent OData: `query.where().eq('Title', 'test').and().contains('Content', 'text').done().order('Title desc')`. Supports `$filter`, `$select`, `$expand`, `$orderby`, `$skip`, `$top`, `$count`, `$search`.
-- **URL handling**: Always normalize with `utils.addTrailingSlash()`. Convert dates to ISO 8601 via `utils.convertDateFieldToISOString()` when sending; incoming responses auto-parse dates via `_parseDateProperties()`.
-- **Sitefinity headers**: Core — `X-Operation`, `X-File-Name`, `X-Sf-Properties` (note: camelCase `Sf`). Upload/advanced — `X-SF-Service-Request`, `X-SF-Integration-Mode`, `X-SF-Binary-Choice-Representation`, `X-SF-Chunk-Ordinal`, `X-SF-Chunk-Size`, `X-SF-File-Size`, `X-SF-Chunked-File-Upload-Session-Id`, `X-SF-Blob-Storage-Provider-Name`. OData params: `sf_provider`, `sf_culture`, `sf_site`, `sf_fallback_prop_names`, `parentId`.
-- **Class naming**: PascalCase (e.g., `RequestFactory`, `BatchRequest`).
-- **Test naming**: `*.spec.ts`. Use Jasmine `describe`/`it`.
-- **HTTP mocking**: `jasmine.Ajax.install()` / `jasmine.Ajax.uninstall()` in `beforeEach` / `afterEach`. Assert against `jasmine.Ajax.requests.mostRecent()`.
-- **Linting**: ESLint with `@typescript-eslint/parser`. `npm run lint`.
-
-## Key Build Commands
-```
-npm start           # Dev server (webpack-dev-server)
-npm run build:dev   # Development build (with source maps)
-npm run build:prod  # Production build (minified)
-npm run test        # Run tests
-npm run docs        # Generate documentation
-```

package/config/helpers.ts

@@ -1,8 +0,0 @@
-const path = require("path");
-
-// Helper functions
-const ROOT = path.resolve(__dirname, "..");
-
-export function root(...args) {
-  return path.join.apply(path, [ROOT].concat(args));
-}

package/config/webpack.common.ts

@@ -1,39 +0,0 @@
-// For instructions about this file refer to
-// webpack and webpack-hot-middleware documentation
-import { Configuration } from "webpack";
-import { root } from "./helpers";
-
-export default (
-    config: Configuration
-) => {
-    delete config["WEBPACK_BUILD"];
-    delete config["WEBPACK_BUNDLE"];
-    delete config["WEBPACK_SERVE"];
-
-    config.name = "Sitefinity";
-    config.mode = "development";
-    config.entry = {
-        "sitefinity-webservices-sdk": root("sitefinity-webservices-sdk")
-    };
-    config.output = {
-        path: root("dist"),
-        filename: "[name].js",
-        chunkFilename: "[name].js",
-        libraryTarget: "umd",
-        library: "Sitefinity",
-        globalObject: "this"
-    };
-    config.resolve = {
-        extensions: [".ts", ".js", ".json", ".html"]
-    };
-    config.module = {
-        rules: [
-            {
-                test: /\.ts$/,
-                use: ["ts-loader"]
-            }
-        ]
-    };
-
-    return config;
-};

package/config/webpack.dev.ts

@@ -1,37 +0,0 @@
-import { Configuration as DevServerConfiguration } from "webpack-dev-server";
-import { Configuration, NoEmitOnErrorsPlugin } from "webpack";
-import commonConfig from "./webpack.common";
-
-const HtmlWebpackPlugin = require("html-webpack-plugin");
-
-
-export default (
-    config: Configuration
-) => {
-    config = commonConfig(config);
-
-    const devServer: DevServerConfiguration = {
-        port: 4000,
-        historyApiFallback: true,
-        open: ["/samples.html"],
-        liveReload: true,
-    };
-
-    config.mode = "development";
-    config.devtool = "source-map";
-    config.devServer = devServer;
-
-    const plugins = [
-        new NoEmitOnErrorsPlugin(),
-        new HtmlWebpackPlugin({
-            filename: "../dist/samples.html",
-            template: "./template.html",
-            inject: "head",
-            scriptLoading: "blocking"
-        })
-    ];
-
-    config.plugins ? config.plugins.push(...plugins) : config.plugins = plugins;
-
-    return config;
-}

package/config/webpack.prod.ts

@@ -1,17 +0,0 @@
-import { Configuration } from "webpack";
-import commonConfig from "./webpack.common";
-
-export default (
-    config: Configuration
-) => {
-    config = commonConfig(config);
-    config.mode = "production";
-    config.output = {
-        filename: "[name].min.js"
-    };
-    config.optimization = {
-        minimize: true
-    }
-
-    return config;
-};

package/dist/docs/.nojekyll

@@ -1 +0,0 @@
-TypeDoc added this file to prevent GitHub Pages from using Jekyll. You can turn off this behavior by setting the `githubPages` option to false.

package/dist/docs/assets/highlight.css

@@ -1,71 +0,0 @@
-:root {
-    --light-hl-0: #000000;
-    --dark-hl-0: #D4D4D4;
-    --light-hl-1: #A31515;
-    --dark-hl-1: #CE9178;
-    --light-hl-2: #0000FF;
-    --dark-hl-2: #569CD6;
-    --light-hl-3: #001080;
-    --dark-hl-3: #9CDCFE;
-    --light-hl-4: #795E26;
-    --dark-hl-4: #DCDCAA;
-    --light-hl-5: #0070C1;
-    --dark-hl-5: #4FC1FF;
-    --light-hl-6: #008000;
-    --dark-hl-6: #6A9955;
-    --light-code-background: #FFFFFF;
-    --dark-code-background: #1E1E1E;
-}
-
-@media (prefers-color-scheme: light) { :root {
-    --hl-0: var(--light-hl-0);
-    --hl-1: var(--light-hl-1);
-    --hl-2: var(--light-hl-2);
-    --hl-3: var(--light-hl-3);
-    --hl-4: var(--light-hl-4);
-    --hl-5: var(--light-hl-5);
-    --hl-6: var(--light-hl-6);
-    --code-background: var(--light-code-background);
-} }
-
-@media (prefers-color-scheme: dark) { :root {
-    --hl-0: var(--dark-hl-0);
-    --hl-1: var(--dark-hl-1);
-    --hl-2: var(--dark-hl-2);
-    --hl-3: var(--dark-hl-3);
-    --hl-4: var(--dark-hl-4);
-    --hl-5: var(--dark-hl-5);
-    --hl-6: var(--dark-hl-6);
-    --code-background: var(--dark-code-background);
-} }
-
-:root[data-theme='light'] {
-    --hl-0: var(--light-hl-0);
-    --hl-1: var(--light-hl-1);
-    --hl-2: var(--light-hl-2);
-    --hl-3: var(--light-hl-3);
-    --hl-4: var(--light-hl-4);
-    --hl-5: var(--light-hl-5);
-    --hl-6: var(--light-hl-6);
-    --code-background: var(--light-code-background);
-}
-
-:root[data-theme='dark'] {
-    --hl-0: var(--dark-hl-0);
-    --hl-1: var(--dark-hl-1);
-    --hl-2: var(--dark-hl-2);
-    --hl-3: var(--dark-hl-3);
-    --hl-4: var(--dark-hl-4);
-    --hl-5: var(--dark-hl-5);
-    --hl-6: var(--dark-hl-6);
-    --code-background: var(--dark-code-background);
-}
-
-.hl-0 { color: var(--hl-0); }
-.hl-1 { color: var(--hl-1); }
-.hl-2 { color: var(--hl-2); }
-.hl-3 { color: var(--hl-3); }
-.hl-4 { color: var(--hl-4); }
-.hl-5 { color: var(--hl-5); }
-.hl-6 { color: var(--hl-6); }
-pre, code { background: var(--code-background); }