impossiblefxv1 1.13.2

package/proto/fx.proto

@@ -0,0 +1,43 @@
+
+import "Movie.proto";
+
+package fx;
+
+extend JetSDL.Proto.Movie {
+	optional string prerender = 1000;
+	optional string postrender = 1001;
+}
+
+extend JetSDL.Proto.Scene {
+	optional string mode = 1000;
+	optional int32 frames = 1001;
+	optional string id = 1002;
+}
+
+extend JetSDL.Proto.VisualTrack {
+	optional string color = 1000;
+}
+
+extend JetSDL.Proto.ImageProvider {
+	optional string type = 1000;
+	optional string ref = 1001;
+}
+
+extend JetSDL.Proto.StringVariable {
+	optional string name = 1000;
+}
+
+message MotionTracker {
+
+}
+
+message Composition{
+	required JetSDL.Proto.Movie movie=1;
+	repeated KVPair meta = 2;
+}
+
+
+message KVPair{
+	optional string key = 1;
+	optional string value = 2;
+}

package/templates/config.html

@@ -0,0 +1,91 @@
+{% extends "templates/docs.html" %}
+
+{% block doc_content %}
+<h1>Configuring the SDK</h1>
+
+<h2>The Configuration Object</h2>
+<p>
+    Configuration in the SDK can be done in two ways:
+    <ol>
+        <li>Global configuration on FX.config, or,</li>
+        <li>Passing extra configuration to a service object</li>
+    </ol>
+
+    Setting global configuration with FX.config is often easier to get up and running with, but service level configuration can provide much more control over your requests. Both of these configuration mechanisms are discussed.
+
+</p>
+
+<h2>Global Configuration</h2>
+<p>
+	By default, you can set global configuration by updating the FX.config object with new settings. The most common settings are:
+    <ul class="topics">
+        <li>apikey, secretkey — for credential management (Only services that require authentication).</li>
+        <li>region — to set the region for requests</li>
+        <li>sslEnabled — whether SSL is enabled or not</li>
+        <li>maxRetries — to control the number of retries for a request</li>
+        <li>logger — a logger object to write debug information to. Set to process.stdout to get logging information about service requests.</li>
+    </ul>     
+</p>		
+
+<p>More configuration settings can be found in the reference documentation.</p>
+
+<p>The only things you need to set in order to use the SDK are credentials and the region value. Let's discuss how to do that.</p>
+
+<h2>Setting Credentials</h2>
+<pre class="prettyprint" style="padding:1em !important">
+FX.config.update({apikey: 'apikey', apisecret: 'apisecret'})
+</pre>
+    
+<h2>Setting the region</h2>
+<pre class="prettyprint" style="padding:1em !important">
+FX.config.update({region: 'us-west-2'})
+</pre>
+
+<h2>Locking API Versions</h2>
+<p class="note">For more information on API version locking in the SDK, see the <a href="workservice.html">Working With Services</a> section.</p>
+
+<p>
+	You can globally configure a set of API versions to use for each service by specifying the <code>apiVersions</code> parameter in FX.config. For example, you can choose to set specific versions of the Project and Render services, while selecting the "latest" version of the Batch Service:
+</p>		
+<pre class="prettyprint" style="padding:1em !important">
+FX.config.apiVersions = {
+  project: '2016-06-02',
+  render: '2016-06-02',
+  batch: 'latest'
+}
+</pre>
+
+<p>
+	Note that by default, the SDK will use the "latest" available API version when constructing a service, i.e. if you don't specify a version.
+</p>		
+
+<p>You can also lock all services at a specific point in time by using a "fuzzy version":</p>
+
+<pre class="prettyprint" style="padding:1em !important">
+// Try to use latest available APIs before this date
+FX.config.apiVersion = '2016-10-12';
+</pre>
+
+<h2>Service-Specific Configuration</h2>
+
+<p>
+	Occasionally, you might want to apply configuration only to one service. For instance, you want to use multiple Project objects in different regions. You can do this by passing configuration data directly to the service object constructor:
+</p>		
+
+<pre class="prettyprint" style="padding:1em !important">
+var sydneyProjects = new FX.Project({region: 'ap-southeast-2', maxRetries: 15});
+</pre>
+
+<p>
+	Note that the constructor takes all of the same configuration data as the FX.config object described above, including credential information.
+</p>		
+
+<h2>Immutable Configuration Data</h2>
+
+<p>Global configuration changes apply to all requests for all newly created services. Any newly created service will merge its local options on top of the global configuration data at the time of creation. This means that any future updates to the global FX.config object will not apply to existing service objects. These services would have to be manually updated with the new configuration data, or recreated using the following command (assuming an existing prj service object):</p>
+
+<pre class="prettyprint" style="padding:1em !important">
+prj = new FX.Project(prj.config);
+</pre>
+
+{% endblock %}

package/templates/examples.html

@@ -0,0 +1,69 @@
+{% extends "templates/docs.html" %}
+
+{% block doc_content %}
+
+<style>
+    code {font-size: 18px; font-weight: bold}
+    .red {color: red}
+</style>
+
+<h1>Common Examples</h1>
+<p>
+    All of these examples assume that the FX SDK is required, credentials are loaded, and the region is set. Some of the examples also assume that you run a HTTP server framework like <a href="http://expressjs.com/">Express</a>, <a href="http://hapijs.com/">Hapi</a> or <a href="https://www.npmjs.com/package/httpdispatcher" >httpdispatcher</a> to handle requests.
+</p>
+
+<p>The common preamble code can be summarized as follows:</p>
+
+<pre class="prettyprint lang-javascript">
+FX = require('impossiblefx-sdk');
+FX.config.apikey = 'APIKEYXXXX';
+FX.config.apisecret = 'ApiSecretXxXxXxX';
+FX.config.region = 'eu-west-1';
+
+express = require('express');
+app = express();
+</pre>    
+
+<h2>Basic Usage</h2>
+<p>The following examples how to request a poster frame from a dynamic movie:</p>
+<pre class="prettyprint lang-javascript">
+var render = new FX.Render({params: {ProjectId: '<span class="red">PROJECT_ID</span>', Movie: '<span class="red">MOVIE_NAME</span>'}});
+var frame_number = 100;
+
+render.getPosterFrameURL({
+    Params: {name: req.query['name']}
+    Frame: <span class="red">frame_number</span>  
+}, function(err, data){
+    console.log("Poster frame URL is:", data.URL)
+})
+</pre>
+
+<h2>Usage in a Node.js Express Server</h2>
+
+<p>The following example shows how to handle a client request, create a FX render request and to return the generated video URL in a server:</p>
+<pre class="prettyprint lang-javascript">
+var render = new FX.Render({params: {ProjectId: '<span class="red">PROJECT_ID</span>', Movie: '<span class="red">MOVIE_NAME</span>'}});
+
+app.get('/video', function(req, res) {
+    render.getRenderURL({
+        Params: {name: req.query['name']}    
+    }, function(err, data){
+        res.send(data.URL)
+    })
+});
+</pre>    
+
+
+<h2>Create a Project and Movie programmatically</h2>
+<p></p>
+<pre class="prettyprint lang-javascript">
+var prj = new FX.Project()
+prj.createProject({Name: "PROJECT_NAME"}, function(err, data){
+    
+})
+</pre>    
+
+
+
+
+{% endblock %}

package/templates/getstarted.html

@@ -0,0 +1,30 @@
+{% extends "templates/docs.html" %}
+
+{% block doc_content %}
+<h1>Getting Started</h1>
+
+<h2>Installation with npm</h2>
+<p>
+    The easiest way to install the FX SDK for Javascript in node.js is to use the <a href="http://npmjs.org">npm Package Manager</a>. 
+</p>
+
+<pre class="prettyprint" style="padding:1em !important">
+npm install impossiblefx
+</pre>
+
+
+<h2>Loading the SDK</h2>
+After you've installed the SDK, you can require the FX package in your node application using require():    
+<pre class="prettyprint" style="padding:1em !important">
+var FX = require('impossiblefx')
+</pre>
+
+<h2>Next Steps</h2>
+<p>
+    Now that you have installed and loaded the SDK, continue on to learn how to configure and use the SDK to make requests to API operations on services.
+</p>
+<ul class="topics">
+    <li><a href="config.html">Configuring the SDK</a></li>
+    <li><a href="makerequests.html">Making Requests</a></li>
+    <li><a href="workservice.html">Working with Services</a></li>
+{% endblock %}

package/templates/index.html

@@ -0,0 +1,6 @@
+<html>
+    <head>
+        <meta http-equiv="refresh" content="0; url=getstarted.html">
+    </head>
+    <h1 style="display:none">Javascript SDK</h1>
+</html>        

package/templates/makeexample.py

@@ -0,0 +1,57 @@
+from cStringIO import StringIO
+
+TypePlaceholder = {
+    'string': "'STRING_VALUE'",
+    'number': "number",
+    'boolean': "true || false",
+    'blob': "Buffer || Stream || Binary",
+    'map': "{{key: value, ...}}",
+    'Movie': "MOVIE_OBJECT",
+    'List<String>': "['Tag1', 'Tag2']"    
+}
+
+
+def makeexample(domain, svcname, opname, operation):
+    input = operation.get('input', {})
+    params = input.get('members', {})
+
+    try:
+        pnames = sorted(params.keys(), reverse=True, key=lambda n: params[n].get('required'))
+
+        io = StringIO()
+        if len(pnames):
+            io.write("var parameters = {{\n")
+            lastName = pnames[-1]
+            for pname in pnames:
+                param = params[pname]
+                if param.get('hidden'):
+                    continue
+                required = ""
+                if param.get('required'):
+                    required = " // required"
+                localName = pname #  pname[0].lower() + pname[1:]
+                io.write("    {}: {}".format(localName, TypePlaceholder[param['type']]))
+                if pname != lastName:
+                    io.write(',')
+                if required:
+                    io.write(required)
+                io.write("\n")
+
+            io.write("}}\n")
+
+        if len(pnames):
+            io.write("{serviceName}.{opname}(parameters, function(err, data) {{")
+        else:
+            io.write("{serviceName}.{opname}(function(err, data) {{")
+            
+        io.write("""
+    if(err) {{
+        console.log(err); // an error occurred
+    }} else {{ 
+        console.log(data);  // successful response
+    }}
+}});
+""")
+        return io.getvalue().format(serviceName=svcname, opname=opname)
+    finally:
+        io.close()

package/templates/makerequests.html

@@ -0,0 +1,210 @@
+{% extends "templates/docs.html" %}
+
+{% block doc_content %}
+<h1>Making Requests</h1>
+<p>
+    A "request" to an FX service includes the full request and response lifecycle of a call to an operation on a service object, including any retries that are transparently attempted on your behalf. A request is encapsulated in the SDK by the FX.Request object. The semantics of a request are described below, specifically, the support for callbacks, events, and streaming of raw HTTP response data.
+</p>
+
+
+<h2>Asynchronous Callbacks</h2>
+<p>
+	All requests made through the SDK are asynchronous and use a callback interface. Each service method that kicks off a request can accept a callback as the last parameter with the signature <code>function(error, data) { ... }</code>. This callback will be called when the response or error data is available.
+</p>		
+
+<p>For example, the following service method can be called with a standard callback to retrieve the response data or error:</p>
+
+<pre class="prettyprint" style="padding:1em !important">
+new FX.Project().listProjects(function(error, data) {
+  if (error) {
+    console.log(error); // an error occurred
+  } else {
+    console.log(data); // request succeeded
+  }
+});
+</pre>
+
+<p>The error and data parameters are described in the "Response Object" section below.</p>
+
+<p>Note that if you do not specify a callback, the operation will return an FX.Request object that must be manually sent using the send() method:</p>
+
+<pre class="prettyprint" style="padding:1em !important">
+// create the FX.Request object
+var request = new FX.Project().listProjects();
+
+// register a callback to report on the data
+request.on('success', function(resp) {
+  console.log(resp.data); // log the successful data response
+});
+
+// send the request
+request.send();
+</pre>
+
+
+<h2>The Response Object (FX.Response)</h2>
+<p>The response object is passed into each callback function so that you can access response data. The FX.Response object that is passed in contains two important properties to get at this data.</p>
+
+<p>When using the standard callback mechanism, the two properties will be made available as parameters on the callback method in the form: <code>function(error, data) { ... }</code></p>
+
+<h3>The <code>data</code> property</h3>
+
+The <code>response.data</code> property contains the serialized object data retrieved from the service request. For instance, for an FX.Project <code>listProjects</code> method call, the response data might look like this:
+
+<pre class="prettyprint" style="padding:1em !important">
+> response.data
+{
+  Projects: [
+    {
+        ProjectId: ...
+        Name: ...
+    },
+
+    {
+        ProjectId: ...
+        Name: ...
+    }
+  ]
+}
+</pre>   
+
+<p>
+	The data property can be null if an error occurs (see below).
+</p>
+
+<h3>The <code>error</code> property</h3>
+        
+
+<p>In the event of a service error (or transfer error), the response.error property will be filled with the given error data in the form:</p>
+
+<pre class="prettyprint" style="padding:1em !important">
+{ code: 'SHORT_UNIQUE_ERROR_CODE',
+  message: 'Some human readable error message' }
+</pre>
+
+<p>In the case of an error, the data property will be null. Note that if you handle events that can be in a failure state, you should always check whether response.error is set before attempting to access the response.data property.</p>
+
+
+<h3>The <code>request</code> property</h3>
+
+<p>Access to the originating request object is available through this property. For example, to access the parameters that were sent with a request:</p>
+
+<pre class="prettyprint" style="padding:1em !important">
+prj.getAsset({Name: 'aName'}).on('success', function(response) {
+  console.log("Name was", response.request.params.Name);
+}).send();
+</pre>
+
+
+<h2>Simplified Callback Method</h2>
+
+<p>Each operation supports a simplified callback that can be passed as the last parameter to any service operation. The callback function should accept an error parameter, followed by the data from the response.</p>
+
+<p>For example:</p>
+<pre class="prettyprint" style="padding:1em !important">
+prj.listProjects(function(error, data) {
+  if (error) {
+    console.log(error); // error is Response.error
+  } else {
+    console.log(data); // data is Response.data
+  }
+});
+</pre>
+
+<p>
+  The error and data parameters accepted are equivalent to the error and data properties discussed in the FX.Response response object section above.
+</p>
+<p>
+	If you are passing parameters to the operation, the callback should be placed after the parameters:
+</p>		
+<pre class="prettyprint" style="padding:1em !important">
+prj.getAsset({ProjectId: '123456789-abcd-4321-98876fecb', 
+              Name: "video.mp4"}, function(error, data) {
+  // ...
+});
+</pre>
+
+<h2>FX.Request Events</h2>
+<p>You can alternatively register callbacks on events provided by the FX.Request object returned by each service operation method. This request object exposes the success and error events, each taking a callback that accepts the response object.</p>
+
+<p>Note that if you omit the simplified callback parameter on the operation method, you must call send() on the returned request object in order to kick off the request to the remote server.</p>
+
+<h3>Event: 'success'</h3>
+<p>This event triggers when a successful response from the server is returned. The response contains a .data field with the serialized response data from the service.</p>
+<pre class="prettyprint" style="padding:1em !important">
+var req = prj.listProjects()
+req.on('success', function(response){
+  console.log(response.data);
+})
+req.send();
+</pre>
+
+<h3>Event: 'error'</h3>
+<p>This event triggers when a successful response from the server is returned. The response contains a .error field with the serialized error data from the service.</p>
+<pre class="prettyprint" style="padding:1em !important">
+var req = prj.listProjects()
+req.on('error', function(response){
+  console.log(response.error);
+})
+req.send();
+</pre>
+
+<h2>Multiple Callbacks and Chaining</h2>
+<p>You can register multiple callbacks on any request object. The callbacks can be registered for different events, or all for the same event. In addition, you can chain callback registration, for example:</p>
+<pre class="prettyprint" style="padding:1em !important">
+prj.listProjects()
+  .on('error', function(response){
+    console.log("Error!");
+  })
+  .on('success', function(response){
+    console.log("Success!");
+  })
+  .on('complete', function(response){
+    console.log("Complete!");
+  })
+  .send();
+</pre>
+<p>
+The above example will print either "Success! Complete!", or "Error! Complete!", depending on whether the request succeeded or not.  
+</p>
+
+<h2>Support for Promises</h2>
+<p>Each operation supports returning a promise if promises are globally available when the SDK in imported or a Promises implementation is provided to the SDK.</p>
+
+
+<h3>Setting a Promise Dependency</h3>
+<p>By default, the SDK will add the promise() method to FX.Request if the Promise constructor is available globally, either natively or pulled in by a 3rd party library. It is also possible to configure the SDK to use a 3rd party implementation of promises, such as bluebird, instead:</p>
+
+<pre class="prettyprint" style="padding:1em !important">
+// Bluebird already loaded
+FX.config.promisesDependency = Promise;
+</pre>
+
+<p>Pass in your favorite Promise library to FX.config.setPromisesDependency or call it without a parameter to revert back to whichever Promise implementation is globally available.</p>
+
+<h2>Returned Promise Method</h2>
+<p>The promise() method is called directly on a FX.Request object. Remember that a request is returned when an operation is called without a callback function supplied. Callbacks can still be registered to events emitted by the request. Calling the promise() method will immediately send then the request, and return a promise that is fulfilled with the response data property or rejected with the response error property:</p>
+
+
+<pre class="prettyprint" style="padding:1em !important">
+// create the FX.Request object
+var request = new FX.Project().listProjects();
+
+// create the promise object
+var promise = request.promise();
+
+// handle promise's fulfilled/rejected states
+promise.then(
+  function(data) {
+    /* process the data */
+  },
+  function(error) {
+    /* handle the error */
+  }
+);
+</pre>
+
+
+
+
+{% endblock %}

package/templates/operation.html

@@ -0,0 +1,36 @@
+{{% extends "templates/docs.html" %}}
+
+{{% block doc_content %}}
+
+<style>
+    code {{font-size: 18px; font-weight: bold}}
+</style>
+
+<h1>{title}</h1>
+<p>
+    {description}
+</p>
+
+<pre class="prettyprint lang-javascript">
+{example}
+</pre>    
+
+<h2>Parameters</h2>
+{params}
+
+<h2>Callback</h2>
+<ul class="api">
+    <li>
+        <code>err</code>
+        <p style="display: inline">(Error) - the error object returned from the request. Set to null if the request is successful.</p>
+    </li>
+    <li>
+        <code>data</code>
+        <p style="display: inline">(Object) — the de-serialized data returned from the request. Set to null if a request error occurs. The data object has the following properties:</p>
+        {result}
+    </li>
+</ul>    
+
+
+
+{{% endblock %}}

package/templates/service.html

@@ -0,0 +1,9 @@
+{{% extends "templates/docs.html" %}}
+
+{{% block doc_content %}}
+<h1>{service}</h1>
+Version: {version}
+<p>
+</p>
+
+{{% endblock %}}

package/templates/services.html

@@ -0,0 +1,19 @@
+{{% extends "templates/docs.html" %}}
+
+{{% block doc_content %}}
+<h1>Service Reference</h1>
+<p>
+    The SDK currently supports the following services:
+</p>
+
+<table class="table table-striped">
+    <tr>
+        <th>Service Name</th>
+        <th>Description</th>
+        <th>Class Name</th>
+        <th>Latest API Version</th>
+    </tr>
+    {services}
+</table>    
+
+{{% endblock %}}

package/templates/version.html

@@ -0,0 +1,12 @@
+{{% extends "templates/docs.html" %}}
+
+{{% block doc_content %}}
+<h1>{version}</h1>
+Name: {name}
+Version: {version}
+
+<p>
+    List of operations
+</p>
+
+{{% endblock %}}

package/templates/versions.html

@@ -0,0 +1,10 @@
+{{% extends "templates/docs.html" %}}
+
+{{% block doc_content %}}
+<h1>Previous Versions</h1>
+
+<p>
+    List of versions
+</p>
+
+{{% endblock %}}

package/templates/workservice.html

@@ -0,0 +1,68 @@
+{% extends "templates/docs.html" %}
+
+{% block doc_content %}
+<h1>Working with Services</h1>
+<p>
+</p>
+<h2>Constructing a Service</h2>
+
+<p>Each service can be constructed with runtime configuration data that is specific to that service object. The service-specific configuration data will be merged on top of global configuration, so there is no need to re-specify any global settings. For example, an Project object can be created for a specific region:</p>
+
+<pre class="prettyprint" style="padding:1em !important">
+var prj = new FX.Project({region: 'us-west-2'});
+</pre>
+
+<p>This object will continue to use the globally provided credentials.</p>
+
+
+<h2>Locking API Versions</h2>
+<p>Services released by Impossible Software use API versions to keep track of API compatibility. API versions in FX services can be identified by a YYYY-mm-dd formatted date string, i.e., 2016-06-02 for the Project Service. It is recommended to lock into an API version for a service if you are relying on it for production code. This way, you can isolate yourself from service changes in updates of the SDK.</p>
+
+<p>In order to lock into an API version of a given service, simply pass the apiVersion parameter when constructing the object, for example:</p>
+
+<pre class="prettyprint" style="padding:1em !important">
+var render = new FX.Render({apiVersion: '2016-06-02'});
+</pre>
+
+<p>Note that versions can also be locked globally by specifying the apiVersion or apiVersions global configuration parameters. This is documented with more detail in the <a href="config.html">Configuring</a> section.</p>
+
+
+
+<h2>Fuzzy Versions and Date Locking</h2>
+
+<p>Since FX has many services with many different API versions, the SDK allows for the specification of "fuzzy versions" instead of exact API version matches. This allows you to specify any date after the API version date, and the SDK will look for the last available matching API version when loading the service object.</p>
+
+<p>You can also use this strategy to globally lock your application to a point in time. For instance, if you begin developing your application on 2016-07-05, you can add the following global apiVersion lock value:</p>
+
+<pre class="prettyprint" style="padding:1em !important">
+FX.config.apiVersion = '2016-07-05';
+</pre>
+
+<p>This will allow all created service objects to use the latest available API versions at the specified lock time. You can override any API versions if you need a newer version, or if the service had not yet been released, by adding the apiVersion parameter to the constructor call as normal:</p>
+
+<pre class="prettyprint" style="padding:1em !important">
+// FX Story Service was not yet released as of 2016-06-02
+var story = new FX.Story({apiVersion: '2016-07-10'});
+</pre>
+
+<h2>Passing Parameters to a Service Operation</h2>
+<p>When calling a method to a service, you should pass parameters in as option values, similar to the way configuration is passed. For example, to get an asset for a given project and name, you can pass the following parameters to the getAsset method:</p>
+
+<pre class="prettyprint" style="padding:1em !important">
+prj.getAsset({ProjectId: '123456-789-abcdef-0123-abcd', Name: 'assetName'});
+</pre>
+
+<p>Note that the full parameter documentation for each method is found in each service page in the complete API reference documentation.</p>
+
+
+<h2>Bound Parameters</h2>
+<p>Parameters can be automatically passed to service operations by binding them directly when constructing the service object. To do this, pass the <code>params</code> parameter to your constructed service with the map of default parameter values like so:</p>
+
+<pre class="prettyprint" style="padding:1em !important">
+var myProject = new FX.Project({ params: {ProjectId: '123456-789-abcdef-0123-abcd'} });
+</pre>
+
+<p>The <code>myProject</code> object will now represent a FX Project service object bound to a project identified by the project ID  <code>'123456-789-abcdef-0123-abcd'</code>. Any operation that takes the <code>projectId</code> parameter will now have it auto-filled with this value. This value can be overridden by passing a new value in the service operation. Additionally, operations that do not require a <code>projectId</code> parameter will automatically ignore this bound parameter, so the <code>myProject</code> object can still be used to call <code>listProjects</code>, for instance.</p>
+
+
+{% endblock %}