Cicero API

Modules

cicero-engine

Clause Engine

cicero-core

Cicero Core - defines the core data types for Cicero.

Classes

Clause

A Clause is executable business logic, linked to a natural language (legally enforceable) template. A Clause must be constructed with a template and then prior to execution the data for the clause must be set. Set the data for the clause (an instance of the template model) by either calling the setData method or by calling the parse method and passing in natural language text that conforms to the template grammar.

Contract

A Contract is executable business logic, linked to a natural language (legally enforceable) template. A Clause must be constructed with a template and then prior to execution the data for the clause must be set. Set the data for the clause (an instance of the template model) by either calling the setData method or by calling the parse method and passing in natural language text that conforms to the template grammar.

Metadata

Defines the metadata for a Template, including the name, version, README markdown.

Template

A template for a legal clause or contract. A Template has a template model, request/response transaction types, a template grammar (natural language for the template) as well as Ergo code for the business logic of the template.

TemplateInstance

A TemplateInstance is an instance of a Clause or Contract template. It is executable business logic, linked to a natural language (legally enforceable) template. A TemplateInstance must be constructed with a template and then prior to execution the data for the clause must be set. Set the data for the TemplateInstance by either calling the setData method or by calling the parse method and passing in natural language text that conforms to the template grammar.

CompositeArchiveLoader

Manages a set of archive loaders, delegating to the first archive loader that accepts a URL.

Functions

isPNG(buffer) ⇒ Boolean

Checks whether the file is PNG

getMimeType(buffer) ⇒ Object

Returns the mime-type of the file

cicero-engine

Clause Engine

• cicero-engine
  • .Engine
    • new Engine()
    • .trigger(clause, request, state, [currentTime], [utcOffset]) ⇒ Promise
    • .invoke(clause, clauseName, params, state, [currentTime], [utcOffset]) ⇒ Promise
    • .init(clause, [currentTime], [utcOffset], params) ⇒ Promise
    • .getErgoEngine() ⇒ ErgoEngine

cicero-engine.Engine

Engine class. Stateless execution of clauses against a request object, returning a response to the caller.

Kind: static class of cicero-engine
Access: public

• .Engine
  • new Engine()
  • .trigger(clause, request, state, [currentTime], [utcOffset]) ⇒ Promise
  • .invoke(clause, clauseName, params, state, [currentTime], [utcOffset]) ⇒ Promise
  • .init(clause, [currentTime], [utcOffset], params) ⇒ Promise
  • .getErgoEngine() ⇒ ErgoEngine

new Engine()

Create the Engine.

engine.trigger(clause, request, state, [currentTime], [utcOffset]) ⇒ Promise

Send a request to a clause for execution

Kind: instance method of Engine
Returns: Promise - a promise that resolves to a result for the clause

Param	Type	Description
clause	Clause	the clause
request	object	the request, a JS object that can be deserialized using the Composer serializer.
state	object	the contract state, a JS object that can be deserialized using the Composer serializer.
[currentTime]	string	the definition of 'now', defaults to current time
[utcOffset]	number	UTC Offset for this execution, defaults to local offset

engine.invoke(clause, clauseName, params, state, [currentTime], [utcOffset]) ⇒ Promise

Invoke a specific clause for execution

Kind: instance method of Engine
Returns: Promise - a promise that resolves to a result for the clause

Param	Type	Description
clause	Clause	the clause
clauseName	string	the clause name
params	object	the clause parameters, a JS object whose fields that can be deserialized using the Composer serializer.
state	object	the contract state, a JS object that can be deserialized using the Composer serializer.
[currentTime]	string	the definition of 'now', defaults to current time
[utcOffset]	number	UTC Offset for this execution, defaults to local offset

engine.init(clause, [currentTime], [utcOffset], params) ⇒ Promise

Initialize a clause

Kind: instance method of Engine
Returns: Promise - a promise that resolves to a result for the clause initialization

Param	Type	Description
clause	Clause	the clause
[currentTime]	string	the definition of 'now', defaults to current time
[utcOffset]	number	UTC Offset for this execution, defaults to local offset
params	object	the clause parameters, a JS object whose fields that can be deserialized using the Composer serializer.

engine.getErgoEngine() ⇒ ErgoEngine

Provides access to the underlying Ergo engine.

Kind: instance method of Engine
Returns: ErgoEngine - the Ergo Engine for this Engine

cicero-core

Cicero Core - defines the core data types for Cicero.

Clause

A Clause is executable business logic, linked to a natural language (legally enforceable) template. A Clause must be constructed with a template and then prior to execution the data for the clause must be set. Set the data for the clause (an instance of the template model) by either calling the setData method or by calling the parse method and passing in natural language text that conforms to the template grammar.

Kind: global class
Access: public

Contract

A Contract is executable business logic, linked to a natural language (legally enforceable) template. A Clause must be constructed with a template and then prior to execution the data for the clause must be set. Set the data for the clause (an instance of the template model) by either calling the setData method or by calling the parse method and passing in natural language text that conforms to the template grammar.

Kind: global class
Access: public

Metadata

Defines the metadata for a Template, including the name, version, README markdown.

Kind: global class
Access: public

• Metadata
  • new Metadata(packageJson, readme, samples, request, logo)
  • instance
    • .getTemplateType() ⇒ number
    • .getLogo() ⇒ Buffer
    • .getAuthor() ⇒ *
    • .getRuntime() ⇒ string
    • .getCiceroVersion() ⇒ string
    • .satisfiesCiceroVersion(version) ⇒ string
    • .getSamples() ⇒ object
    • .getRequest() ⇒ object
    • .getSample(locale) ⇒ string
    • .getREADME() ⇒ String
    • .getPackageJson() ⇒ object
    • .getName() ⇒ string
    • .getDisplayName() ⇒ string
    • .getKeywords() ⇒ Array
    • .getDescription() ⇒ string
    • .getVersion() ⇒ string
    • .getIdentifier() ⇒ string
    • .createTargetMetadata(runtimeName) ⇒ object
    • .toJSON() ⇒ object
  • static
    • .checkImage(buffer)
    • .checkImageDimensions(buffer, mimeType)

new Metadata(packageJson, readme, samples, request, logo)

Create the Metadata.

Note: Only to be called by framework code. Applications should retrieve instances from [Template](#Template)

Param	Type	Description
packageJson	object	the JS object for package.json (required)
readme	String	the README.md for the template (may be null)
samples	object	the sample markdown for the template in different locales,
request	object	the JS object for the sample request
logo	Buffer	the bytes data for the image represented as an object whose keys are the locales and whose values are the sample markdown. For example: { default: 'default sample markdown', en: 'sample text in english', fr: 'example de texte français' } Locale keys (with the exception of default) conform to the IETF Language Tag specification (BCP 47). THe default key represents sample template text in a non-specified language, stored in a file called sample.md.

metadata.getTemplateType() ⇒ number

Returns either a 0 (for a contract template), or 1 (for a clause template)

Kind: instance method of Metadata
Returns: number - the template type

metadata.getLogo() ⇒ Buffer

Returns the logo at the root of the template

Kind: instance method of Metadata
Returns: Buffer - the bytes data of logo

metadata.getAuthor() ⇒ *

Returns the author for this template.

Kind: instance method of Metadata
Returns: * - the author information

metadata.getRuntime() ⇒ string

Returns the name of the runtime target for this template, or null if this template has not been compiled for a specific runtime.

Kind: instance method of Metadata
Returns: string - the name of the runtime

metadata.getCiceroVersion() ⇒ string

Returns the version of Cicero that this template is compatible with. i.e. which version of the runtime was this template built for? The version string conforms to the semver definition

Kind: instance method of Metadata
Returns: string - the semantic version

metadata.satisfiesCiceroVersion(version) ⇒ string

Only returns true if the current cicero version satisfies the target version of this template

Kind: instance method of Metadata
Returns: string - the semantic version

Param	Type	Description
version	string	the cicero version to check against

metadata.getSamples() ⇒ object

Returns the samples for this template.

Kind: instance method of Metadata
Returns: object - the sample files for the template

metadata.getRequest() ⇒ object

Returns the sample request for this template.

Kind: instance method of Metadata
Returns: object - the sample request for the template

metadata.getSample(locale) ⇒ string

Returns the sample for this template in the given locale. This may be null. If no locale is specified returns the default sample if it has been specified.

Kind: instance method of Metadata
Returns: string - the sample file for the template in the given locale or null

Param	Type	Default	Description
locale	string	null	the IETF language code for the language.

metadata.getREADME() ⇒ String

Returns the README.md for this template. This may be null if the template does not have a README.md

Kind: instance method of Metadata
Returns: String - the README.md file for the template or null

metadata.getPackageJson() ⇒ object

Returns the package.json for this template.

Kind: instance method of Metadata
Returns: object - the Javascript object for package.json

metadata.getName() ⇒ string

Returns the name for this template.

Kind: instance method of Metadata
Returns: string - the name of the template

metadata.getDisplayName() ⇒ string

Returns the display name for this template.

Kind: instance method of Metadata
Returns: string - the display name of the template

metadata.getKeywords() ⇒ Array

Returns the keywords for this template.

Kind: instance method of Metadata
Returns: Array - the keywords of the template

metadata.getDescription() ⇒ string

Returns the description for this template.

Kind: instance method of Metadata
Returns: string - the description of the template

metadata.getVersion() ⇒ string

Returns the version for this template.

Kind: instance method of Metadata
Returns: string - the description of the template

metadata.getIdentifier() ⇒ string

Returns the identifier for this template, formed from name@version.

Kind: instance method of Metadata
Returns: string - the identifier of the template

metadata.createTargetMetadata(runtimeName) ⇒ object

Return new Metadata for a target runtime

Kind: instance method of Metadata
Returns: object - the new Metadata

Param	Type	Description
runtimeName	string	the target runtime name

metadata.toJSON() ⇒ object

Return the whole metadata content, for hashing

Kind: instance method of Metadata
Returns: object - the content of the metadata object

Metadata.checkImage(buffer)

Check the buffer is a png file with the right size

Kind: static method of Metadata

Param	Type	Description
buffer	Buffer	the buffer object

Metadata.checkImageDimensions(buffer, mimeType)

Checks if dimensions for the image are correct.

Kind: static method of Metadata

Param	Type	Description
buffer	Buffer	the buffer object
mimeType	string	the mime type of the object

Template

A template for a legal clause or contract. A Template has a template model, request/response transaction types, a template grammar (natural language for the template) as well as Ergo code for the business logic of the template.

Kind: global abstract class
Access: public

• Template
  • new Template(packageJson, readme, samples, request, logo, options, authorSignature)
  • instance
    • .validate(options)
    • .getTemplateModel() ⇒ ClassDeclaration
    • .getIdentifier() ⇒ String
    • .getMetadata() ⇒ Metadata
    • .getName() ⇒ String
    • .getDisplayName() ⇒ string
    • .getVersion() ⇒ String
    • .getDescription() ⇒ String
    • .getHash() ⇒ string
    • .verifyTemplateSignature()
    • .signTemplate(p12File, passphrase, timestamp)
    • .toArchive([language], [options]) ⇒ Promise.<Buffer>
    • .getParserManager() ⇒ ParserManager
    • .getLogicManager() ⇒ LogicManager
    • .getIntrospector() ⇒ Introspector
    • .getFactory() ⇒ Factory
    • .getSerializer() ⇒ Serializer
    • .getRequestTypes() ⇒ Array
    • .getResponseTypes() ⇒ Array
    • .getEmitTypes() ⇒ Array
    • .getStateTypes() ⇒ Array
    • .hasLogic() ⇒ boolean
  • static
    • .fromDirectory(path, [options]) ⇒ Promise.<Template>
    • .fromArchive(buffer, [options]) ⇒ Promise.<Template>
    • .fromUrl(url, [options]) ⇒ Promise
    • .instanceOf(classDeclaration, fqt) ⇒ boolean

new Template(packageJson, readme, samples, request, logo, options, authorSignature)

Create the Template. Note: Only to be called by framework code. Applications should retrieve instances from fromArchive or fromDirectory.

Param	Type	Description
packageJson	object	the JS object for package.json
readme	String	the readme in markdown for the template (optional)
samples	object	the sample text for the template in different locales
request	object	the JS object for the sample request
logo	Buffer	the bytes data of logo
options	Object	e.g., { warnings: true }
authorSignature	Object	object containing template hash, timestamp, author's certificate, signature

template.validate(options)

Verifies that the template is well formed. Compiles the Ergo logic. Throws an exception with the details of any validation errors.

Kind: instance method of Template

Param	Type	Description
options	Object	e.g., { verify: true }

template.getTemplateModel() ⇒ ClassDeclaration

Returns the template model for the template

Kind: instance method of Template
Returns: ClassDeclaration - the template model for the template
Throws:

• Error if no template model is found, or multiple template models are found

template.getIdentifier() ⇒ String

Returns the identifier for this template

Kind: instance method of Template
Returns: String - the identifier of this template

template.getMetadata() ⇒ Metadata

Returns the metadata for this template

Kind: instance method of Template
Returns: Metadata - the metadata for this template

template.getName() ⇒ String

Returns the name for this template

Kind: instance method of Template
Returns: String - the name of this template

template.getDisplayName() ⇒ string

Returns the display name for this template.

Kind: instance method of Template
Returns: string - the display name of the template

template.getVersion() ⇒ String

Returns the version for this template

Kind: instance method of Template
Returns: String - the version of this template. Use semver module to parse.

template.getDescription() ⇒ String

Returns the description for this template

Kind: instance method of Template
Returns: String - the description of this template

template.getHash() ⇒ string

Gets a content based SHA-256 hash for this template. Hash is based on the metadata for the template plus the contents of all the models and all the script files.

Kind: instance method of Template
Returns: string - the SHA-256 hash in hex format

template.verifyTemplateSignature()

verifies the signature stored in the template object using the template hash and timestamp

Kind: instance method of Template

template.signTemplate(p12File, passphrase, timestamp)

signs a string made up of template hash and time stamp using private key derived from the keystore

Kind: instance method of Template

Param	Type	Description
p12File	String	encoded string of p12 keystore file
passphrase	String	passphrase for the keystore file
timestamp	Number	timestamp of the moment of signature is done

template.toArchive([language], [options]) ⇒ Promise.<Buffer>

Persists this template to a Cicero Template Archive (cta) file.

Kind: instance method of Template
Returns: Promise.<Buffer> - the zlib buffer

Param	Type	Description
[language]	string	target language for the archive (should be 'ergo')
[options]	Object	JSZip options and keystore object containing path and passphrase for the keystore

template.getParserManager() ⇒ ParserManager

Provides access to the parser manager for this template. The parser manager can convert template data to and from natural language text.

Kind: instance method of Template
Returns: ParserManager - the ParserManager for this template

template.getLogicManager() ⇒ LogicManager

Provides access to the template logic for this template. The template logic encapsulate the code necessary to execute the clause or contract.

Kind: instance method of Template
Returns: LogicManager - the LogicManager for this template

template.getIntrospector() ⇒ Introspector

Provides access to the Introspector for this template. The Introspector is used to reflect on the types defined within this template.

Kind: instance method of Template
Returns: Introspector - the Introspector for this template

template.getFactory() ⇒ Factory

Provides access to the Factory for this template. The Factory is used to create the types defined in this template.

Kind: instance method of Template
Returns: Factory - the Factory for this template

template.getSerializer() ⇒ Serializer

Provides access to the Serializer for this template. The Serializer is used to serialize instances of the types defined within this template.

Kind: instance method of Template
Returns: Serializer - the Serializer for this template

template.getRequestTypes() ⇒ Array

Provides a list of the input types that are accepted by this Template. Types use the fully-qualified form.

Kind: instance method of Template
Returns: Array - a list of the request types

template.getResponseTypes() ⇒ Array

Provides a list of the response types that are returned by this Template. Types use the fully-qualified form.

Kind: instance method of Template
Returns: Array - a list of the response types

template.getEmitTypes() ⇒ Array

Provides a list of the emit types that are emitted by this Template. Types use the fully-qualified form.

Kind: instance method of Template
Returns: Array - a list of the emit types

template.getStateTypes() ⇒ Array

Provides a list of the state types that are expected by this Template. Types use the fully-qualified form.

Kind: instance method of Template
Returns: Array - a list of the state types

template.hasLogic() ⇒ boolean

Returns true if the template has logic, i.e. has more than one script file.

Kind: instance method of Template
Returns: boolean - true if the template has logic

Template.fromDirectory(path, [options]) ⇒ Promise.<Template>

Builds a Template from the contents of a directory. The directory must include a package.json in the root (used to specify the name, version and description of the template).

Kind: static method of Template
Returns: Promise.<Template> - a Promise to the instantiated template

Param	Type	Default	Description
path	String		to a local directory
[options]	Object		an optional set of options to configure the instance.

Template.fromArchive(buffer, [options]) ⇒ Promise.<Template>

Create a template from an archive.

Kind: static method of Template
Returns: Promise.<Template> - a Promise to the template

Param	Type	Default	Description
buffer	Buffer		the buffer to a Cicero Template Archive (cta) file
[options]	Object		an optional set of options to configure the instance.

Template.fromUrl(url, [options]) ⇒ Promise

Create a template from an URL.

Kind: static method of Template
Returns: Promise - a Promise to the template

Param	Type	Default	Description
url	String		the URL to a Cicero Template Archive (cta) file
[options]	Object		an optional set of options to configure the instance.

Template.instanceOf(classDeclaration, fqt) ⇒ boolean

Check to see if a ClassDeclaration is an instance of the specified fully qualified type name.

Kind: static method of Template
Returns: boolean - True if classDeclaration an instance of the specified fully qualified type name, false otherwise.
Internal:

Param	Type	Description
classDeclaration	ClassDeclaration	The class to test
fqt	String	The fully qualified type name.

TemplateInstance

A TemplateInstance is an instance of a Clause or Contract template. It is executable business logic, linked to a natural language (legally enforceable) template. A TemplateInstance must be constructed with a template and then prior to execution the data for the clause must be set. Set the data for the TemplateInstance by either calling the setData method or by calling the parse method and passing in natural language text that conforms to the template grammar.

Kind: global abstract class
Access: public

• TemplateInstance
  • new TemplateInstance(template)
  • instance
    • .setData(data)
    • .getData() ⇒ object
    • .getEngine() ⇒ object
    • .getDataAsConcertoObject() ⇒ object
    • .parse(input, [currentTime], [utcOffset], [fileName])
    • .draft([options], [currentTime], [utcOffset]) ⇒ string
    • .formatCiceroMark(ciceroMarkParsed, options, format) ⇒ string
    • .getIdentifier() ⇒ String
    • .getTemplate() ⇒ Template
    • .getLogicManager() ⇒ LogicManager
    • .toJSON() ⇒ object
  • static
    • .ciceroFormulaEval(logicManager, clauseId, ergoEngine, name) ⇒ *
    • .rebuildParser(parserManager, logicManager, ergoEngine, templateName, grammar)

new TemplateInstance(template)

Create the Clause and link it to a Template.

Param	Type	Description
template	Template	the template for the clause

templateInstance.setData(data)

Set the data for the clause

Kind: instance method of TemplateInstance

Param	Type	Description
data	object	the data for the clause, must be an instance of the template model for the clause's template. This should be a plain JS object and will be deserialized and validated into the Concerto object before assignment.

templateInstance.getData() ⇒ object

Get the data for the clause. This is a plain JS object. To retrieve the Concerto object call getConcertoData().

Kind: instance method of TemplateInstance
Returns: object - - the data for the clause, or null if it has not been set

templateInstance.getEngine() ⇒ object

Get the current Ergo engine

Kind: instance method of TemplateInstance
Returns: object - - the data for the clause, or null if it has not been set

templateInstance.getDataAsConcertoObject() ⇒ object

Get the data for the clause. This is a Concerto object. To retrieve the plain JS object suitable for serialization call toJSON() and retrieve the data property.

Kind: instance method of TemplateInstance
Returns: object - - the data for the clause, or null if it has not been set

templateInstance.parse(input, [currentTime], [utcOffset], [fileName])

Set the data for the clause by parsing natural language text.

Kind: instance method of TemplateInstance

Param	Type	Description
input	string	the text for the clause
[currentTime]	string	the definition of 'now', defaults to current time
[utcOffset]	number	UTC Offset for this execution, defaults to local offset
[fileName]	string	the fileName for the text (optional)

templateInstance.draft([options], [currentTime], [utcOffset]) ⇒ string

Generates the natural language text for a contract or clause clause; combining the text from the template and the instance data.

Kind: instance method of TemplateInstance
Returns: string - the natural language text for the contract or clause; created by combining the structure of the template with the JSON data for the clause.

Param	Type	Description
[options]	*	text generation options.
[currentTime]	string	the definition of 'now', defaults to current time
[utcOffset]	number	UTC Offset for this execution, defaults to local offset

templateInstance.formatCiceroMark(ciceroMarkParsed, options, format) ⇒ string

Format CiceroMark

Kind: instance method of TemplateInstance
Returns: string - the result of parsing and printing back the text

Param	Type	Description
ciceroMarkParsed	object	the parsed CiceroMark DOM
options	object	parameters to the formatting
format	string	to the text generation

templateInstance.getIdentifier() ⇒ String

Returns the identifier for this clause. The identifier is the identifier of the template plus '-' plus a hash of the data for the clause (if set).

Kind: instance method of TemplateInstance
Returns: String - the identifier of this clause

templateInstance.getTemplate() ⇒ Template

Returns the template for this clause

Kind: instance method of TemplateInstance
Returns: Template - the template for this clause

templateInstance.getLogicManager() ⇒ LogicManager

Returns the template logic for this clause

Kind: instance method of TemplateInstance
Returns: LogicManager - the template for this clause

templateInstance.toJSON() ⇒ object

Returns a JSON representation of the clause

Kind: instance method of TemplateInstance
Returns: object - the JS object for serialization

TemplateInstance.ciceroFormulaEval(logicManager, clauseId, ergoEngine, name) ⇒ *

Constructs a function for formula evaluation based for this template instance

Kind: static method of TemplateInstance
Returns: * - A function from formula code + input data to result

Param	Type	Description
logicManager	*	the logic manager
clauseId	string	this instance identifier
ergoEngine	*	the evaluation engine
name	string	the name of the formula

TemplateInstance.rebuildParser(parserManager, logicManager, ergoEngine, templateName, grammar)

Utility to rebuild a parser when the grammar changes

Kind: static method of TemplateInstance

Param	Type	Description
parserManager	*	the parser manager
logicManager	*	the logic manager
ergoEngine	*	the evaluation engine
templateName	string	this template name
grammar	string	the new grammar

CompositeArchiveLoader

Manages a set of archive loaders, delegating to the first archive loader that accepts a URL.

Kind: global class

• CompositeArchiveLoader
  • new CompositeArchiveLoader()
  • .addArchiveLoader(archiveLoader)
  • .clearArchiveLoaders()
  • .accepts(url) ⇒ boolean
  • .load(url, options) ⇒ Promise

new CompositeArchiveLoader()

Create the CompositeArchiveLoader. Used to delegate to a set of ArchiveLoaders.

compositeArchiveLoader.addArchiveLoader(archiveLoader)

Adds a ArchiveLoader implementation to the ArchiveLoader

Kind: instance method of CompositeArchiveLoader

Param	Type	Description
archiveLoader	ArchiveLoader	The archive to add to the CompositeArchiveLoader

compositeArchiveLoader.clearArchiveLoaders()

Remove all registered ArchiveLoaders

Kind: instance method of CompositeArchiveLoader

compositeArchiveLoader.accepts(url) ⇒ boolean

Returns true if this ArchiveLoader can process the URL

Kind: instance abstract method of CompositeArchiveLoader
Returns: boolean - true if this ArchiveLoader accepts the URL

Param	Type	Description
url	string	the URL

compositeArchiveLoader.load(url, options) ⇒ Promise

Load a Archive from a URL and return it

Kind: instance method of CompositeArchiveLoader
Returns: Promise - a promise to the Archive

Param	Type	Description
url	string	the url to get
options	object	additional options

isPNG(buffer) ⇒ Boolean

Checks whether the file is PNG

Kind: global function
Returns: Boolean - whether the file in PNG

Param	Type	Description
buffer	Buffer	buffer of the file

getMimeType(buffer) ⇒ Object

Returns the mime-type of the file

Kind: global function
Returns: Object - the mime-type of the file

Param	Type	Description
buffer	Buffer	buffer of the file