@progress/sitefinity-webservices-sdk 1.1.16 → 2.0.0

package/src/Requests/BatchRequest.d.ts

@@ -0,0 +1,174 @@
+import { RequestFactory } from "./RequestFactory";
+import { ExecutableRequest } from "./ExecutableRequest";
+import { AuthorizationToken, SDKOptions, TypeOptions } from "../Sitefinity";
+import { RequestBase, RequestOptionsBaseExtended } from "./RequestBase";
+import { CreateRelatedRequestOptions, RequestOptionsBase, PropertyRequestOptions, SingleRelatedItemRequestOptions, CreateRequestOptions, UpdateRequestOptions } from "../Data";
+import { HttpTransportResponse } from "../Transport/HttpTransport";
+/**
+ * Groups data-modifying requests into one atomic OData changeset.
+ *
+ * This is an advanced API. Add requests to a transaction, pass it to `BatchRequest.endTransaction`,
+ * and execute the batch. Request IDs become MIME `Content-ID` values and can be used for links.
+ */
+export declare class Transaction {
+    /** Batch-local transaction identifier and MIME content ID. */
+    id: number;
+    /** Next request ID allocated by this transaction. */
+    counter: number;
+    /** Requests currently included in the transaction. */
+    requests: TransactionRequest[];
+    private urlOptions;
+    private factory;
+    /** Creates an empty transaction using the batch URL options and request factory. */
+    constructor(urlOptions: TypeOptions, factory: RequestFactory);
+    /** Adds a file upload and returns its batch-local request ID. */
+    upload(parameters: any): number;
+    /**
+    * Adds a create request and returns its batch-local request ID.
+    *
+    * @throws When `entitySet` is missing.
+    */
+    create(parameters: BatchCreateRequestOptions): number;
+    /** Adds an operation request. Validation errors are thrown when required values are missing. */
+    operation(parameters: BatchCreateRequestOptions): void;
+    /** Adds an update request. Validation errors are thrown when required values are missing. */
+    update(parameters: BatchUpdateRequestOptions): void;
+    /** Adds a delete request. Validation errors are thrown when required values are missing. */
+    destroy(parameters: BatchSingleItemRequestOptions): void;
+    /** Adds a request that removes all links in a related property. */
+    destroyRelated(parameters: BatchPropertyRequestOptions): void;
+    /** Adds a request that removes one related link by key. */
+    destroyRelatedById(parameters: BatchSingleRelatedItemRequestOptions): void;
+    /** Adds a related-link request and returns its batch-local request ID. */
+    createRelated(parameters: BatchCreateRelatedRequestOptions): number;
+    private overrideUrlGeneration;
+    private addRequest;
+    private urlParametersClone;
+}
+/**
+ * Groups requests into one multipart/mixed `$batch` request.
+ *
+ * This is an advanced API. Add operations, optionally group writes in a transaction, then call
+ * `execute()`. The success callback receives parsed results with status, headers, data, and keys.
+ */
+export declare class BatchRequest extends ExecutableRequest {
+    /** Next batch-local request or transaction ID. */
+    counter: number;
+    /** Requests and transactions included in this batch. */
+    requests: BatchInnerRequest[];
+    private factory;
+    private boundary;
+    private responseHeaderRegex;
+    private responseStatusRegex;
+    /** Protocol constants used when constructing multipart MIME content. */
+    static constants: {
+        newLine: string;
+    };
+    /** Creates an empty batch request. */
+    constructor(requestOptions: BatchRequestOptionsExtended, token: AuthorizationToken, sdkOptions: SDKOptions);
+    /** Adds a collection GET request. Validation errors are thrown for missing `entitySet`. */
+    get(parameters: BatchRequestOptionsBase): void;
+    /** Adds a single-item GET request. Validation errors are thrown for missing keys. */
+    getSingle(parameters: BatchSingleItemRequestOptions): void;
+    /** Adds a related-property GET request. */
+    getProperty(parameters: BatchPropertyRequestOptions): void;
+    /** Adds a related-items GET request. */
+    getRelated(parameters: BatchPropertyRequestOptions): void;
+    /** Adds a GET request for one related item by key. */
+    getRelatedById(parameters: BatchSingleRelatedItemRequestOptions): void;
+    /** Starts an atomic transaction changeset to add to this batch. */
+    beginTransaction(): Transaction;
+    /** Adds a transaction changeset to the batch. Empty transactions are omitted from the body. */
+    endTransaction(transaction: Transaction): void;
+    /** Builds the multipart MIME body sent to the `$batch` endpoint. */
+    getBody(): object;
+    /** Returns `POST`, the HTTP method used for the `$batch` endpoint. */
+    getMethod(): string;
+    /** Returns headers with the generated multipart MIME content type. */
+    getHeaders(): {
+        [key: string]: string;
+    };
+    /** Builds the `$batch` URL and appends any configured query parameters. */
+    buildUrl(): string;
+    protected parseResponse(response: HttpTransportResponse): any;
+    private parseBatchResponse;
+    private getResponseResult;
+    private currentBoundary;
+    private contentType;
+    private readTo;
+    private readLine;
+    private readHeaders;
+    private readResponse;
+    private buildRequestBody;
+    private buildRequest;
+    private buildTransaction;
+    private createDelimeter;
+    private createBoundary;
+    private addRequest;
+    private urlParametersClone;
+}
+interface TransactionRequest {
+    id: number;
+    request: RequestBase;
+}
+interface BatchInnerRequest {
+    id: number;
+    request: RequestBase | Transaction;
+}
+/**
+ * Low-level construction options for a batch request.
+ */
+export interface BatchRequestOptionsExtended extends RequestOptionsBaseExtended {
+    /** Factory used to create the individual requests in the batch. */
+    factory: RequestFactory;
+}
+/**
+ * Common options for adding an operation to a batch.
+ */
+export interface BatchRequestOptionsBase extends RequestOptionsBase {
+    /** Entity set addressed by the batch operation. */
+    entitySet: string;
+}
+/**
+ * Options for adding an item-creation operation to a transaction.
+ */
+export interface BatchCreateRequestOptions extends CreateRequestOptions {
+    /** Entity set containing the item to create. */
+    entitySet: string;
+}
+/**
+ * Options for adding an item-update operation to a transaction.
+ */
+export interface BatchUpdateRequestOptions extends UpdateRequestOptions {
+    /** Entity set containing the item to update. */
+    entitySet: string;
+}
+/**
+ * Options for adding a single-item operation to a batch or transaction.
+ */
+export interface BatchSingleItemRequestOptions extends RequestOptionsBase {
+    /** Entity set containing the addressed item. */
+    entitySet: string;
+}
+/**
+ * Options for adding a property or relation operation to a batch or transaction.
+ */
+export interface BatchPropertyRequestOptions extends PropertyRequestOptions {
+    /** Entity set containing the addressed item. */
+    entitySet: string;
+}
+/**
+ * Options for adding a single-related-item operation to a batch or transaction.
+ */
+export interface BatchSingleRelatedItemRequestOptions extends SingleRelatedItemRequestOptions {
+    /** Entity set containing the addressed item. */
+    entitySet: string;
+}
+/**
+ * Options for adding a related-item creation operation to a transaction.
+ */
+export interface BatchCreateRelatedRequestOptions extends CreateRelatedRequestOptions {
+    /** Entity set containing the addressed item. */
+    entitySet: string;
+}
+export {};

package/src/Requests/ExecutableRequest.d.ts

@@ -0,0 +1,43 @@
+import { RequestBase, RequestOptionsBaseExtended } from "./RequestBase";
+import { AuthorizationToken, SDKOptions } from "../Sitefinity";
+import { HttpTransportProgressEvent } from "../Transport/HttpTransport";
+/**
+ * Request base class that executes an asynchronous HTTP request through the configured transport.
+ *
+ * This is an advanced API. Execution uses callbacks rather than promises and invokes the configured
+ * success, failure, and progress handlers when appropriate.
+ */
+export declare class ExecutableRequest extends RequestBase {
+    private token;
+    private enableUnlimitedChoices;
+    private integrationMode;
+    private transport;
+    /**
+     * Creates an executable request with authentication and SDK-wide execution options.
+     *
+     * @param requestOptions Request URL, query, data, and callback options.
+     * @param token Optional bearer token or legacy authorization header value.
+     * @param sdkOptions SDK-wide handlers and request behavior options.
+     */
+    constructor(requestOptions: RequestOptionsBaseExtended, token: AuthorizationToken, sdkOptions: SDKOptions);
+    /**
+     * Sends the request asynchronously.
+     *
+     * Successful responses are passed to `successCb`; HTTP errors are normalized and passed to
+     * `failureCb`. The method returns immediately and does not return a promise or response value.
+     */
+    execute(): void;
+    /** Maps the transport's upload progress event to the value passed to `progressCb`. */
+    protected getProgressPayload(event: HttpTransportProgressEvent): object;
+    private handleResponse;
+    private buildHeaders;
+}
+/**
+ * Default success and failure callbacks for SDK requests.
+ */
+export interface ResponseHandlers {
+    /** Callback invoked with the parsed successful response. */
+    successCb?: Function;
+    /** Callback invoked with the parsed error response and HTTP status. */
+    failureCb?: Function;
+}

package/src/Requests/Request.d.ts

@@ -0,0 +1,225 @@
+import { AuthorizationToken, SDKOptions } from "../Sitefinity";
+import { ExecutableRequest } from "./ExecutableRequest";
+import { RequestOptionsBaseExtended } from "./RequestBase";
+/** Low-level request for retrieving a collection of items. */
+export declare class GetRequest extends ExecutableRequest {
+    /** Creates a collection GET request. */
+    constructor(requestOptions: RequestOptionsBaseExtended, token: AuthorizationToken, sdkOptions: SDKOptions);
+    /** Returns `GET`, the HTTP method used by this request. */
+    getMethod(): string;
+}
+/** Low-level request for retrieving one item by key. */
+export declare class GetByIdRequest extends ExecutableRequest {
+    /** Creates a single-item GET request. */
+    constructor(requestOptions: RequestOptionsBaseExtended, token: AuthorizationToken, sdkOptions: SDKOptions);
+    /** Returns `GET`, the HTTP method used by this request. */
+    getMethod(): string;
+}
+/** Low-level request for deleting one item. */
+export declare class DeleteRequest extends ExecutableRequest {
+    /** Creates a DELETE request. */
+    constructor(requestOptions: RequestOptionsBaseExtended, token: AuthorizationToken, sdkOptions: SDKOptions);
+    /** Returns `DELETE`, the HTTP method used by this request. */
+    getMethod(): string;
+}
+/** Low-level request for updating one item with PATCH. */
+export declare class UpdateRequest extends ExecutableRequest {
+    private data;
+    private saveTemp;
+    /** Creates an update request, optionally using the Sitefinity temporary-save operation. */
+    constructor(requestOptions: PutRequestOptionsExtended, token: AuthorizationToken, sdkOptions: SDKOptions);
+    /** Returns `PATCH`, the HTTP method used by this request. */
+    getMethod(): string;
+    /** Returns the update payload after converting date values to ISO strings. */
+    getBody(): object;
+    getHeaders(): {
+        [key: string]: string;
+    };
+}
+/** Low-level request for creating one item with POST. */
+export declare class CreateRequest extends ExecutableRequest {
+    protected data: object;
+    /** Creates a request containing the item data to post. */
+    constructor(requestOptions: PostRequestOptionsExtended, token: AuthorizationToken, sdkOptions: SDKOptions);
+    /** Returns `POST`, the HTTP method used by this request. */
+    getMethod(): string;
+    /** Returns the create payload after converting date values to ISO strings. */
+    getBody(): object;
+}
+/** Low-level request for retrieving all values in a related property. */
+export declare class GetRelatedRequest extends GetByIdRequest {
+    private property;
+    /** Creates a related-property GET request. */
+    constructor(requestOptions: RelatedRequestOptionsExtended, token: AuthorizationToken, sdkOptions: SDKOptions);
+    buildUrl(): string;
+}
+/** Low-level request for retrieving one related value by key. */
+export declare class GetRelatedByIdRequest extends GetByIdRequest {
+    private property;
+    private relatedId;
+    /** Creates a related-item GET request. */
+    constructor(requestOptions: RelatedByIdRequestOptionsExtended, token: AuthorizationToken, sdkOptions: SDKOptions);
+    buildUrl(): string;
+}
+/** Low-level request for removing all links in a related property. */
+export declare class DeleteRelatedRequest extends DeleteRequest {
+    private property;
+    /** Creates a related-property DELETE request. */
+    constructor(requestOptions: RelatedRequestOptionsExtended, token: AuthorizationToken, sdkOptions: SDKOptions);
+    buildUrl(): string;
+}
+/** Low-level request for removing one related link by key. */
+export declare class DeleteRelatedByIdRequest extends DeleteRequest {
+    private property;
+    private relatedId;
+    /** Creates a related-item DELETE request. */
+    constructor(requestOptions: RelatedByIdRequestOptionsExtended, token: AuthorizationToken, sdkOptions: SDKOptions);
+    buildUrl(): string;
+}
+/** Low-level request for adding a link to a related property. */
+export declare class CreateRelatedRequest extends CreateRequest {
+    private property;
+    /** Creates a related-property POST request. */
+    constructor(requestOptions: RelatedRequestOptionsExtended, token: AuthorizationToken, sdkOptions: SDKOptions);
+    buildUrl(): string;
+}
+/** Low-level request for uploading a file or binary payload. */
+export declare class UploadRequest extends CreateRequest {
+    private fileName;
+    private uploadProperties;
+    private contentType;
+    /** Creates an upload request with MIME type, file name, and upload properties. */
+    constructor(requestOptions: UploadRequestOptionsExtended, token: AuthorizationToken, sdkOptions: SDKOptions);
+    /** Returns upload headers, including the MIME type, encoded file name, and properties. */
+    getHeaders(): {
+        [key: string]: string;
+    };
+    /** Returns the binary upload payload without JSON date conversion. */
+    getBody(): object;
+    /** Returns `POST` for new files or `PATCH` when updating an existing item. */
+    getMethod(): string;
+}
+/** Low-level request for uploading one chunk of a file. */
+export declare class UploadChunkRequest extends CreateRequest {
+    /** MIME type sent for the chunk. */
+    contentType: string;
+    /** Ordinal of the chunk being uploaded. */
+    chunkOrdinal: number;
+    chunkSize: number;
+    /** Identifier shared by all chunks in the upload session. */
+    chunkedFileUploadSessionId: string;
+    /** Total number of chunks in the upload. */
+    numberOfChunks: number;
+    /** Queue position used for synthetic progress events. */
+    positionInQueue: number;
+    /** Blob storage provider handling the upload. */
+    blobStorageProviderName: string;
+    /** Original file name sent with the chunk. */
+    fileName: string;
+    /** Creates a chunk upload request. */
+    constructor(requestOptions: UploadChunkRequestOptionsExtended, token: AuthorizationToken, sdkOptions: SDKOptions);
+    /** Returns chunk headers required by the Sitefinity chunk upload service. */
+    getHeaders(): {
+        [key: string]: string;
+    };
+    /** Returns the binary content of this chunk. */
+    getBody(): object;
+    /** Returns `POST`, the HTTP method used for a chunk. */
+    getMethod(): string;
+    /** Reports chunk progress as the position in the upload queue rather than bytes sent. */
+    protected getProgressPayload(): object;
+}
+/** Low-level request for committing all chunks in an upload session. */
+export declare class CommitChunksRequest extends CreateRequest {
+    /** Creates a chunk-commit request and its server operation payload. */
+    constructor(requestOptions: CommitChunksRequestOptionsExtended, token: AuthorizationToken, sdkOptions: SDKOptions);
+    /** Returns `POST`, the HTTP method used to commit the upload. */
+    getMethod(): string;
+}
+/**
+ * Extended options for low-level POST requests.
+ */
+export interface PostRequestOptionsExtended extends RequestOptionsBaseExtended {
+    /** Item or operation payload sent in the request body. */
+    data?: object;
+}
+/**
+ * Extended options for low-level update requests.
+ */
+export interface PutRequestOptionsExtended extends PostRequestOptionsExtended {
+    /** Sends the Sitefinity `SaveTemp` operation header when true. */
+    saveTemp: boolean;
+}
+/**
+ * Extended options for low-level relation requests.
+ */
+export interface RelatedRequestOptionsExtended extends PostRequestOptionsExtended {
+    /** Related property name addressed by the request. */
+    property: string;
+}
+/**
+ * Extended options for low-level requests that address one related item.
+ */
+export interface RelatedByIdRequestOptionsExtended extends RelatedRequestOptionsExtended {
+    /** Key of the related item addressed by the request. */
+    relatedId: string;
+}
+/**
+ * Extended options for low-level file upload requests.
+ */
+export interface UploadRequestOptionsExtended extends PostRequestOptionsExtended {
+    /** File name sent in the upload headers. */
+    fileName: string;
+    /** MIME type sent in the `Content-Type` header. */
+    contentType: string;
+    /** Sitefinity properties serialized into the upload request headers. */
+    uploadProperties: {
+        [key: string]: string;
+    };
+}
+/**
+ * Extended options for uploading one chunk of a file.
+ */
+export interface UploadChunkRequestOptionsExtended extends PostRequestOptionsExtended {
+    /** MIME type of the complete file. */
+    fileMimeType: string;
+    /** Original file name. */
+    fileName: string;
+    /** Identifier of the chunked upload session. */
+    chunkedFileUploadSessionId: string;
+    /** Size of each uploaded chunk in bytes. */
+    chunkSize: number;
+    /** Ordinal of the chunk being uploaded. */
+    chunkOrdinal: number;
+    /** Total number of chunks in the upload. */
+    numberOfChunks: number;
+    /** Binary content for this chunk. */
+    chunkBlob: Blob;
+    /** Name of the blob storage provider. */
+    blobStorageProviderName: string;
+    /** Optional queue position used for progress reporting. */
+    positionOfChunkInQueue?: number;
+}
+/**
+ * Extended options for committing a completed chunk-upload session.
+ */
+export interface CommitChunksRequestOptionsExtended extends PostRequestOptionsExtended {
+    /** Identifier of the chunked upload session. */
+    chunkedFileUploadSessionId: string;
+    /** Name of the blob storage provider. */
+    blobStorageProviderName: string;
+    /** MIME type of the committed file. */
+    contentType: string;
+    /** Total file size in bytes. */
+    fileTotalSize: number;
+    /** Number of chunks uploaded. */
+    numberOfChunks: number;
+    /** Original file name. */
+    fileName: string;
+    /** Sitefinity properties associated with the uploaded file. */
+    uploadProperties: {
+        [key: string]: string;
+    };
+    /** Existing item key when committing an update. */
+    itemId?: string;
+}

package/src/Requests/RequestBase.d.ts

@@ -0,0 +1,58 @@
+import { RequestOptionsBase } from "../Data";
+import { Query } from "../Query";
+import { TypeOptions } from "../Sitefinity";
+import { HttpTransportResponse } from "../Transport/HttpTransport";
+/**
+ * Base class for low-level Sitefinity requests.
+ *
+ * This is an advanced API. Most consumers should use the fluent methods on the SDK data services.
+ */
+export declare class RequestBase {
+    /** Callback invoked with the parsed response after a successful request. */
+    successCb: Function;
+    /** Callback invoked with the parsed error response when the request fails. */
+    failureCb: Function;
+    /** Callback invoked with upload progress events, when supported by the request. */
+    progressCb: Function;
+    /** Entity key used to address a single item, when applicable. */
+    key: string | number;
+    /** URL, provider, culture, site, and header options used to build the request. */
+    urlOptions: TypeOptions;
+    protected query: Query;
+    protected action: string;
+    private fallbackProperties;
+    /**
+     * Creates a low-level request from its URL, query, callback, and entity options.
+     *
+     * @param options Request options used to build and execute the request.
+     */
+    constructor(options: RequestOptionsBaseExtended);
+    /**
+     * Builds the encoded OData and Sitefinity query string for the request.
+     *
+     * @param urlOptions URL options whose provider, culture, site, and extra parameters are included.
+     * @param query OData query options to include.
+     * @returns A query string beginning with `?`, or `null` when no parameters apply.
+     */
+    getQueryString(urlOptions: TypeOptions, query: Query): string;
+    /** Returns the request body. Subclasses override this for requests with content. */
+    getBody(): object;
+    /** Returns the HTTP method used by the request. */
+    getMethod(): string;
+    /** Returns the headers used by the request, including a JSON content type by default. */
+    getHeaders(): {
+        [key: string]: string;
+    };
+    /** Builds the request URL, including the entity key, action, count path, and query string. */
+    buildUrl(): string;
+    protected parseResponse(response: HttpTransportResponse): string | any;
+    protected addQueryParameters(url: string): string;
+    private getQueryParameters;
+}
+/**
+ * Request-construction options shared by concrete low-level request classes.
+ */
+export interface RequestOptionsBaseExtended extends RequestOptionsBase {
+    /** URL and entity-set options used to build the request. */
+    urlOptions: TypeOptions;
+}

package/{dist/src → src}/Requests/RequestFactory.d.ts

@@ -1,24 +1,46 @@
 import { GetRequest, GetByIdRequest, CreateRequest, UpdateRequest, DeleteRequest, GetRelatedRequest, GetRelatedByIdRequest, DeleteRelatedRequest, DeleteRelatedByIdRequest, CreateRelatedRequest, UploadRequest, PostRequestOptionsExtended, PutRequestOptionsExtended, RelatedRequestOptionsExtended, RelatedByIdRequestOptionsExtended, UploadRequestOptionsExtended, UploadChunkRequest, CommitChunksRequest, CommitChunksRequestOptionsExtended, UploadChunkRequestOptionsExtended } from "./Request";
-import { SDKOptions, Token } from "../Sitefinity";
+import { AuthorizationToken, SDKOptions } from "../Sitefinity";
 import { BatchRequest } from "./BatchRequest";
 import { RequestOptionsBaseExtended } from "./RequestBase";
+/**
+ * Creates low-level request objects for data, relation, upload, and batch operations.
+ *
+ * This is an advanced API. Requests must be executed explicitly and report results through callbacks.
+ */
 export declare class RequestFactory {
-    token: Token;
+    /** Authentication token applied to requests created by this factory. */
+    token: AuthorizationToken;
     private options;
+    /** Creates a request factory using the supplied SDK-wide options. */
     constructor(options: SDKOptions);
+    /** Creates a request for retrieving a collection. */
     get(parameters: RequestOptionsBaseExtended): GetRequest;
+    /** Creates a request for retrieving one item by key. */
     getSingle(parameters: RequestOptionsBaseExtended): GetByIdRequest;
+    /** Creates a request for creating one item. */
     create(parameters: PostRequestOptionsExtended): CreateRequest;
+    /** Creates a request for updating one item. */
     update(parameters: PutRequestOptionsExtended): UpdateRequest;
+    /** Creates a request for deleting one item. */
     destroy(parameters: RequestOptionsBaseExtended): DeleteRequest;
+    /** Creates a request for retrieving a related property value. */
     getProperty(parameters: RelatedRequestOptionsExtended): GetRelatedRequest;
+    /** Creates a request for retrieving related items. */
     getRelated(parameters: RelatedRequestOptionsExtended): GetRelatedRequest;
+    /** Creates a request for retrieving one related item by key. */
     getRelatedById(parameters: RelatedByIdRequestOptionsExtended): GetRelatedByIdRequest;
+    /** Creates a request for removing all related links for a property. */
     destroyRelated(parameters: RelatedRequestOptionsExtended): DeleteRelatedRequest;
+    /** Creates a request for removing one related link by key. */
     destroyRelatedById(parameters: RelatedByIdRequestOptionsExtended): DeleteRelatedByIdRequest;
+    /** Creates a request for adding a related link. */
     createRelated(parameters: RelatedRequestOptionsExtended): CreateRelatedRequest;
+    /** Creates a request for uploading a file or binary payload. */
     upload(parameters: UploadRequestOptionsExtended): UploadRequest;
+    /** Creates a request for uploading one file chunk. */
     uploadChunk(parameters: UploadChunkRequestOptionsExtended): UploadChunkRequest;
+    /** Creates a request that commits an uploaded chunk session. */
     commitChunks(parameters: CommitChunksRequestOptionsExtended): CommitChunksRequest;
+    /** Creates a multipart batch request; call its methods to add operations, then call `execute()`. */
     batch(parameters: RequestOptionsBaseExtended): BatchRequest;
 }