@sitevision/api 1.0.19 → 1.1.0-alpha.1

package/server/RestApi/index.d.ts

@@ -1,47 +1,232 @@
-import Node from '../../builtins/Node';
+import Node from "../../hidden/javax/jcr/Node";
 
-interface IRestApiResult {
-  statusCode: any;
-  statusMessage: string;
-  body: any;
-}
-
-// function delete(aContextNode: Node, aOperationName: string): RestApiResult
-// function delete(aContextNode: Node, aOperationName: string, aOperationNode: Node): RestApiResult
+/**
+ * Executes a GET endpoint of the REST API.
+ *
+ * <p>
+ *    <em>REST hint!</em> A <em>get</em> typically indicates a <em>read</em> of something.
+ * </p>
+ * @param aContextNode the endpoint context Node
+ * @param aOperationName the endpoint operation name/method
+ * @return a script object representing the response (properties: statusCode, statusMessage, body)
+ */
+export function get(aContextNode: Node, aOperationName: string): unknown;
 
-export function get(aContextNode: Node, aOperationName: string): IRestApiResult;
+/**
+ * Executes a GET endpoint of the REST API.
+ *
+ * <p>
+ *    <em>REST hint!</em> A <em>get</em> typically indicates a <em>read</em> of something.
+ * </p>
+ * @param aContextNode the endpoint context Node
+ * @param aOperationName the endpoint operation name/method
+ * @param aOperationOptions the operation data/parameters
+ * @return a script object representing the response (properties: statusCode, statusMessage, body)
+ */
 export function get(
   aContextNode: Node,
   aOperationName: string,
-  aOperationNode: Node
-): IRestApiResult;
+  aOperationOptions: unknown
+): unknown;
+
+/**
+ * Executes a GET endpoint of the REST API, targeting an instance of the context.
+ *
+ * <p>
+ *    <em>REST hint!</em> A <em>get</em> typically indicates a <em>read</em> of something.
+ * </p>
+ * @param aContextNode the endpoint context Node
+ * @param aOperationName the endpoint operation name/method
+ * @param aOperationNode the operation Node of the context
+ * @param aOperationOptions the operation data/parameters
+ * @return a script object representing the response (properties: statusCode, statusMessage, body)
+ */
 export function get(
   aContextNode: Node,
   aOperationName: string,
   aOperationNode: Node,
-  aOperationOptions: any
-): IRestApiResult;
+  aOperationOptions: unknown
+): unknown;
 
+/**
+ * Executes a POST endpoint of the REST API.
+ *
+ * <p>
+ *    <em>REST hint!</em> A <em>post</em> typically indicates the <em>creation</em> of something.
+ * </p>
+ * @param aContextNode the endpoint context Node
+ * @param aOperationName the endpoint operation name/method
+ * @param aOperationOptions the operation data/parameters
+ * @return a script object representing the response (properties: statusCode, statusMessage, body)
+ */
 export function post(
   aContextNode: Node,
   aOperationName: string,
-  aOperationNode: Node
-): IRestApiResult;
+  aOperationOptions: unknown
+): unknown;
 
+/**
+ * Executes a PUT endpoint of the REST API.
+ *
+ * <p>
+ *    <em>REST hint!</em> A <em>put</em> typically indicates an <em>update</em> of something.
+ * </p>
+ * @param aContextNode the endpoint context Node
+ * @param aOperationName the endpoint operation name/method
+ * @param aOperationOptions the operation data/parameters
+ * @return a script object representing the response (properties: statusCode, statusMessage, body)
+ * @since Sitevision 5
+ */
 export function put(
   aContextNode: Node,
   aOperationName: string,
-  aOperationNode: Node
-): IRestApiResult;
+  aOperationOptions: unknown
+): unknown;
+
+/**
+ * Executes a PUT endpoint of the REST API, targeting an instance of the context.
+ *
+ * <p>
+ *    <em>REST hint!</em> A <em>put</em> typically indicates an <em>update</em> of something.
+ * </p>
+ * @param aContextNode the endpoint context Node
+ * @param aOperationName the endpoint operation name/method
+ * @param aOperationNode the operation Node of the context
+ * @param aOperationOptions the operation data/parameters
+ * @return a script object representing the response (properties: statusCode, statusMessage, body)
+ */
 export function put(
   aContextNode: Node,
   aOperationName: string,
   aOperationNode: Node,
-  aOperationOptions: any
-): IRestApiResult;
+  aOperationOptions: unknown
+): unknown;
+
+/**
+ * Executes a DELETE endpoint of the REST API.
+ *
+ * <p>
+ *    <em>REST hint!</em> A <em>delete</em> typically indicates a <em>removal</em> of something.
+ * </p>
+ * @param aContextNode the endpoint context Node
+ * @param aOperationName the endpoint operation name/method
+ * @return a script object representing the response (properties: statusCode, statusMessage, body)
+ * @since Sitevision 4.5.1
+ */
+declare function _delete(aContextNode: Node, aOperationName: string): unknown;
+export { _delete as delete };
+
+/**
+ * Executes a DELETE endpoint of the REST API, targeting an instance of the context.
+ *
+ * <p>
+ *    <em>REST hint!</em> A <em>delete</em> typically indicates a <em>removal</em> of something.
+ * </p>
+ * @param aContextNode the endpoint context Node
+ * @param aOperationName the endpoint operation name/method
+ * @param aOperationNode the operation Node of the context
+ * @return a script object representing the response (properties: statusCode, statusMessage, body)
+ */
+declare function _delete(
+  aContextNode: Node,
+  aOperationName: string,
+  aOperationNode: Node
+): unknown;
+export { _delete as delete };
 
-declare namespace restApi {
-  export { get, post, put };
+/**
+ * Script utility for server-side invoke of the local Sitevision REST API.
+ *
+ * <p>
+ *    This is a local, server-side, inbound utility to invoke the
+ *    <a href="https://developer.sitevision.se/docs/rest-api/model-rest-api" target="_blank">Sitevision REST API</a>
+ *    of the local site without any outgoing http connections.
+ *    This utility can be used regardless of the REST API of the local site is enabled or not!
+ * </p>
+ *
+ * <p>
+ *    <strong>Version note!</strong> External (http connection-based) invocations of the Sitevision REST API can specify different versions
+ *    (online / offline) via the URL. This inbound utility will always use <em>current version</em> as of
+ *    {@link senselogic.sitevision.api.versioning.VersionUtil#getCurrentVersion()}.
+ * </p>
+ *
+ * <p>
+ *    Below are two typical examples of how to use the RestApi utility to execute a GET for the "nodes" endpoint on a given JCR Node
+ *    context and and process the returned javascript object.
+ * </p>
+ * <p>
+ *    <em>a) Using a Node via a script variable (named "startPage") in the Sitevision Script module:</em>
+ * </p>
+ * <pre><code>   var restApi = require('RestApi'),
+ *       result;
+ *
+ *   result = restApi.get(scriptVariables.startPage, 'nodes');
+ *
+ *   if (result.statusCode &gt;= 200 &amp;&amp; result.statusCode &lt; 300) {
+ *      out.println('Result: ' + JSON.stringify(result.body));
+ *   } else {
+ *      out.println('Fail: ' + result.statusMessage + '&lt;br&gt;' + JSON.stringify(result.body));
+ *   }</code></pre>
+ * <p>
+ *    <em>b) Using a Node via the app data (property "startPage") of a WebApp/RestApp:</em>
+ * </p>
+ * <pre><code>   ...
+ *   result = restApi.get(appData.getNode('startPage'), 'nodes');
+ *   ...</code></pre>
+ *
+ * <p>
+ *    <strong>REST siblings note!</strong>
+ * </p>
+ * <ul>
+ *    <li>
+ *       Server-side invoke of a <em>local RESTApp</em> should typically be handled via
+ *       {@link senselogic.sitevision.api.script.app.RestAppInvoker}.
+ *    </li>
+ *    <li>
+ *       Invoking <em>external REST API:s</em> should typically be handled via
+ *       {@link senselogic.sitevision.api.script.Requester}.
+ *    </li>
+ * </ul>Executes a GET endpoint of the REST API.
+ *
+ * <p>
+ *    <em>REST hint!</em> A <em>get</em> typically indicates a <em>read</em> of something.
+ * </p>Executes a GET endpoint of the REST API.
+ *
+ * <p>
+ *    <em>REST hint!</em> A <em>get</em> typically indicates a <em>read</em> of something.
+ * </p>Executes a GET endpoint of the REST API, targeting an instance of the context.
+ *
+ * <p>
+ *    <em>REST hint!</em> A <em>get</em> typically indicates a <em>read</em> of something.
+ * </p>Executes a POST endpoint of the REST API.
+ *
+ * <p>
+ *    <em>REST hint!</em> A <em>post</em> typically indicates the <em>creation</em> of something.
+ * </p>Executes a PUT endpoint of the REST API.
+ *
+ * <p>
+ *    <em>REST hint!</em> A <em>put</em> typically indicates an <em>update</em> of something.
+ * </p>Executes a PUT endpoint of the REST API, targeting an instance of the context.
+ *
+ * <p>
+ *    <em>REST hint!</em> A <em>put</em> typically indicates an <em>update</em> of something.
+ * </p>Executes a DELETE endpoint of the REST API.
+ *
+ * <p>
+ *    <em>REST hint!</em> A <em>delete</em> typically indicates a <em>removal</em> of something.
+ * </p>Executes a DELETE endpoint of the REST API, targeting an instance of the context.
+ *
+ * <p>
+ *    <em>REST hint!</em> A <em>delete</em> typically indicates a <em>removal</em> of something.
+ * </p>
+ * @param <O> script object
+ * @author Magnus Lövgren
+ * @since Sitevision 4.5
+ * @see Requester
+ * @see senselogic.sitevision.api.script.app.RestAppInvoker
+ */
+declare namespace RestApi {
+  export { get, post, put, _delete as delete };
 }
 
-export default restApi;
+export default RestApi;

package/server/RestAppInvokerFactory/index.d.ts

@@ -0,0 +1,73 @@
+import RestAppInvoker from "../../hidden/senselogic/sitevision/api/script/app/RestAppInvoker";
+import Node from "../../hidden/javax/jcr/Node";
+
+/**
+ * Creates a RestAppInvoker via the Path of a Headless custom module.
+ * @param aPath the path of the Headless custom module (sv:headlessCustomModule or sv:marketplaceHeadlessCustomModule)
+ * @return the RestAppInvoker for the active RESTApp of the module, or null if no matching RESTApp could be found
+ */
+export function fromPath(aPath: string): RestAppInvoker;
+
+/**
+ * Creates a RestAppInvoker via a RESTApp Node or a Headless custom module Node.
+ * @param aNode the RESTApp (sv:restApp) or the Headless custom module (sv:headlessCustomModule or sv:marketplaceHeadlessCustomModule)
+ * @return the RestAppInvoker for the RESTApp, or null if no matching RESTApp could be found
+ */
+export function fromNode(aNode: Node): RestAppInvoker;
+
+/**
+ * Creates a RestAppInvoker via the Identifier of a RESTApp or a Headless custom module.
+ * @param aIdentifier the identifier of the RESTApp (sv:restApp) or the Headless custom module (sv:headlessCustomModule or sv:marketplaceHeadlessCustomModule), i.e. an identifier prefixed with "361.", "188." or "211.".
+ * @return the RestAppInvoker for the resolved RESTApp, or null if no matching RESTApp could be found
+ */
+export function fromIdentifier(aIdentifier: string): RestAppInvoker;
+
+/**
+ * Creates RestAppInvoker instances.
+ *
+ * <h3>
+ *    Some code examples
+ * </h3>
+ * <p>
+ *    Below is an example of how to get a {@link RestAppInvoker} instance using the path (of the headless custom module).
+ * </p><pre><code>   var restAppInvokerFactory = require('RestAppInvokerFactory'),
+ *       restAppInvoker = restAppInvokerFactory.fromPath('/rest-api/my-rest-app');
+ *
+ *    if (restAppInvoker) {
+ *       <em>// Use the RESTApp invoker...</em>
+ *    }</code></pre>
+ *
+ * <p>
+ *    Below is an example of how to get a {@link RestAppInvoker} instance using a Node. Note that the Node must be of type
+ *    <code>sv:restApp</code>, <code>sv:headlessCustomModule</code> or <code>sv:marketplaceHeadlessCustomModule</code>.
+ * </p><pre><code>   var restAppInvokerFactory = require('RestAppInvokerFactory'),
+ *       restAppInvoker = restAppInvokerFactory.fromNode(aNode);
+ *
+ *    if (restAppInvoker) {
+ *       <em>// Use the RESTApp invoker...</em>
+ *    }</code></pre>
+ *
+ * <p>
+ *    Below is an example of how to get a {@link RestAppInvoker} instance using a Node identifier. Note that the identifier must be for a Node of type
+ *    <code>sv:restApp</code>, <code>sv:headlessCustomModule</code> or <code>sv:marketplaceHeadlessCustomModule</code>
+ *    (i.e. an identifier prefixed "361.", "188." or "211.").
+ * </p><pre><code>   var restAppInvokerFactory = require('RestAppInvokerFactory'),
+ *       restAppInvoker = restAppInvokerFactory.fromIdentifier(aIdentifier);
+ *
+ *    if (restAppInvoker) {
+ *       <em>// Use the RESTApp invoker...</em>
+ *    }</code></pre>
+ *
+ * <p>
+ *    See {@link RestAppInvoker} for more code examples.
+ * </p>Creates a RestAppInvoker via the Path of a Headless custom module.Creates a RestAppInvoker via a RESTApp Node or a Headless custom module Node.Creates a RestAppInvoker via the Identifier of a RESTApp or a Headless custom module.
+ * @param <O> script object
+ * @author Magnus Lövgren
+ * @since Sitevision 7
+ * @see RestAppInvoker
+ */
+declare namespace RestAppInvokerFactory {
+  export { fromPath, fromNode, fromIdentifier };
+}
+
+export default RestAppInvokerFactory;

package/server/RoleAssignmentBuilder/index.d.ts

@@ -0,0 +1,60 @@
+import Node from "../../hidden/javax/jcr/Node";
+import RoleAssignment from "../../hidden/senselogic/sitevision/api/security/RoleAssignment";
+
+/**
+ * Sets the principal (sv:user, sv:simpleUser, sv:userGroup or sv:virtualGroup).
+ * @param aPrincipal the principal
+ * @return this builder
+ */
+export function setPrincipal(aPrincipal: Node): RoleAssignmentBuilder;
+
+/**
+ * Sets the role (sv:role).
+ * @param aRole the role
+ * @return this builder
+ */
+export function setRole(aRole: Node): RoleAssignmentBuilder;
+
+/**
+ * Clears the state of this builder.
+ *
+ * <p>
+ *    Sets the <em>principal</em> and the <em>role</em> to null.
+ * </p>
+ * @return this builder
+ */
+export function clear(): RoleAssignmentBuilder;
+
+/**
+ * Creates a read-only RoleAssignment instance using current state of this builder.
+ * @return a RoleAssignment instance
+ * @throws IllegalStateException if role and/or principal is not properly set
+ */
+export function build(): RoleAssignment;
+
+/**
+ * Builder of RoleAssignment instances.
+ *
+ * <p>
+ *    <em>Tip!</em> The {@link senselogic.sitevision.api.base.Builder Builder interface documentation} contains
+ *    more information about Builders and how to work with them!
+ * </p>
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via
+ *    {@link RoleUtil#getRoleAssignmentBuilder()}.
+ *    See {@link RoleUtil} for how to obtain an instance of the <code>RoleUtil</code> interface.
+ * </p>Sets the principal (sv:user, sv:simpleUser, sv:userGroup or sv:virtualGroup).Sets the role (sv:role).Clears the state of this builder.
+ *
+ * <p>
+ *    Sets the <em>principal</em> and the <em>role</em> to null.
+ * </p>Creates a read-only RoleAssignment instance using current state of this builder.
+ * @author Magnus Lövgren
+ * @since Sitevision 5.1
+ * @see RoleAssignment
+ */
+declare namespace RoleAssignmentBuilder {
+  export { setPrincipal, setRole, clear, build };
+}
+
+export default RoleAssignmentBuilder;

package/server/RoleMatcherBuilder/index.d.ts

@@ -0,0 +1,59 @@
+import Node from "../../hidden/javax/jcr/Node";
+import RoleMatcher from "../../hidden/senselogic/sitevision/api/security/RoleMatcher";
+
+/**
+ * Sets the user (sv:user, sv:simpleUser).
+ * @param aUser the user
+ * @return this builder
+ */
+export function setUser(aUser: Node): RoleMatcherBuilder;
+
+/**
+ * Adds a role (sv:role).
+ * @param aRole the role to add
+ * @return this builder
+ */
+export function addRole(aRole: Node): RoleMatcherBuilder;
+
+/**
+ * Clears the state of this builder.
+ *
+ * <p>
+ *    Sets the <em>user</em> and the <em>roles</em> to null.
+ * </p>
+ * @return this builder
+ */
+export function clear(): RoleMatcherBuilder;
+
+/**
+ * Creates a read-only RoleMatcher instance using current state of this builder.
+ * @return a RoleMatcher instance
+ * @throws IllegalStateException if user is not properly set or if no roles are added
+ */
+export function build(): RoleMatcher;
+
+/**
+ * Builder of RoleMatcher instances.
+ *
+ * <p>
+ *    <em>Tip!</em> The {@link senselogic.sitevision.api.base.Builder Builder interface documentation} contains
+ *    more information about Builders and how to work with them!
+ * </p>
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via
+ *    {@link RoleUtil#getRoleMatcherBuilder()}.
+ *    See {@link RoleUtil} for how to obtain an instance of the <code>RoleUtil</code> interface.
+ * </p>Sets the user (sv:user, sv:simpleUser).Adds a role (sv:role).Clears the state of this builder.
+ *
+ * <p>
+ *    Sets the <em>user</em> and the <em>roles</em> to null.
+ * </p>Creates a read-only RoleMatcher instance using current state of this builder.
+ * @author Magnus Lövgren
+ * @since Sitevision 6.1
+ */
+declare namespace RoleMatcherBuilder {
+  export { setUser, addRole, clear, build };
+}
+
+export default RoleMatcherBuilder;

package/server/RoleUtil/index.d.ts

@@ -0,0 +1,57 @@
+import RoleAssignmentBuilder from "../RoleAssignmentBuilder";
+import RoleMatcherBuilder from "../RoleMatcherBuilder";
+import Node from "../../hidden/javax/jcr/Node";
+import PermissionUtil_Permission from "../PermissionUtil_Permission";
+
+/**
+ * Creates a RoleAssignmentBuilder instance.
+ * @return a RoleAssignmentBuilder
+ */
+export function getRoleAssignmentBuilder(): RoleAssignmentBuilder;
+
+/**
+ * Creates a RoleMatcherBuilder instance.
+ * @return a RoleMatcherBuilder
+ * @since Sitevision 6.1
+ */
+export function getRoleMatcherBuilder(): RoleMatcherBuilder;
+
+/**
+ * Gets a role by name.
+ * @param aRoleName the name of the role
+ * @return the role (sv:role) with name aRoleName, or null if no such role could be found
+ */
+export function getRoleByName(aRoleName: string): Node;
+
+/**
+ * Checks if a role contains a specific permission.
+ * @param aRole the role (sv:role)
+ * @param aPermission the permission
+ * @return true if aRole is a sv:role and contains aPermission, false otherwise
+ */
+export function containsPermission(
+  aRole: Node,
+  aPermission: Permission
+): boolean;
+
+/**
+ * Role utility interface.
+ *
+ * <p>
+ *    An instance of the Sitevision class implementing this interface can be obtained via {@link senselogic.sitevision.api.Utils#getRoleUtil()}.
+ *    See {@link senselogic.sitevision.api.Utils} for how to obtain an instance of the <code>Utils</code> interface.
+ * </p>Creates a RoleAssignmentBuilder instance.Creates a RoleMatcherBuilder instance.Gets a role by name.Checks if a role contains a specific permission.
+ * @author Magnus Lövgren
+ * @since Sitevision 5.1
+ * @see PermissionUtil
+ */
+declare namespace RoleUtil {
+  export {
+    getRoleAssignmentBuilder,
+    getRoleMatcherBuilder,
+    getRoleByName,
+    containsPermission,
+  };
+}
+
+export default RoleUtil;