autoingesttool v2.1.1

autoingesttool

Apple Auto-Ingest tool written in JavaScript for NodeJS.

Prerequesites

Download the iTunes Connect Sales And Trends Guide Apps PDF file.

Dependencies

• is-my-json-valid : A JSONSchema validator that uses code generation to be extremely fast.
• mkdirp : Recursively mkdir, like "mkdir -p".
• async : Higher-order functions and common patterns for asynchronous code.
• request : Simplified HTTP request client.
• moment : Parse, manipulate, and display dates.
• clone : Deep cloning of objects and arrays.
• lodash : Lodash modular utilities

Features

• Automatic validation of all parameters.
• Asynchronous report download.
• Automatic extraction of downloaded report archive.
• Automatic creation of report file formatted in JSON.
• Choose where all files will be created.
• Downloading cancelled if archive already exists.
• Extraction cancelled if text file already exists.
• Promise support for sales and financial reports download

Installation

$ npm install [--save] autoingesttool

Usage

First you need to import the module.

var AutoIngestTool = require("autoingesttool");

Create a JSON object with all required parameters for Sales report.

// Sales
var parameters = {
	username: "admin",
	password: "adminpasswd",
	vendor_number: "88776655",
	report_type: "Sales",
	report_subtype: "Summary",
	date_type: "Daily",
	report_date: "20160201"
};

Or you can create a JSON object to download Financial report.

// Financial
var parameters = {
	username: "admin",
	password: "adminpasswd",
	vendor_number: "0088776655",
	report_type: "DRR",
	region_code: "US",
	fiscal_year: 2014,
	fiscal_period: 1
};

Then you need to create another JSON object with the paths where the archive will be downloaded, extracted and transformed. IMPORTANT : All parameters are required.

var paths = {
	archive: "/path/to/archive",
    report: "/path/to/extracted/archive",
    json_report: "/path/to/transformed/archive"
};

You can now call the desired method to download a Sales report or a Financial report.

// Download Sales report
AutoIngestTool.downloadSalesReport(salesParams, paths, function (err, updatedPaths) {
  if (err && (err instanceof AutoIngestTool.INVALID_PARAMETERS_ERROR))
    // Handle error
  if (err && (err instanceof AutoIngestTool.INVALID_PATHS_ERROR))
    // Handle error
  if (err && (err instanceof AutoIngestTool.EMPTY_FILE_ERROR))
    // Handle error
  if (err)
    // Handle error

  console.log(updatedPaths);
});

// Download Sales report using promise
AutoIngestTool.downloadSalesReport(salesParams, paths).then(
  function(paths) {
    console.log(paths);
  },
  function(err) {
    if (err && (err instanceof AutoIngestTool.INVALID_PARAMETERS_ERROR))
      // Handle error
    if (err && (err instanceof AutoIngestTool.INVALID_PATHS_ERROR))
      // Handle error
    if (err && (err instanceof AutoIngestTool.EMPTY_FILE_ERROR))
      // Handle error

    console.log(err);
  }
);

// Download Financial report
AutoIngestTool.downloadFinancialReport(financialParams, paths, function (err, updatedPaths) {
  if (err && (err instanceof AutoIngestTool.INVALID_PARAMETERS_ERROR))
    // Handle error
  if (err && (err instanceof AutoIngestTool.INVALID_PATHS_ERROR))
    // Handle error
  if (err && (err instanceof AutoIngestTool.EMPTY_FILE_ERROR))
    // Handle error
  if (err)
    // Handle error

  console.log(updatedPaths);
});

// Download Financial report using promise
AutoIngestTool.downloadSalesReport(financialParams, paths).then(
  function(paths) {
    console.log(paths);
  },
  function(err) {
    if (err && (err instanceof AutoIngestTool.INVALID_PARAMETERS_ERROR))
      // Handle error
    if (err && (err instanceof AutoIngestTool.INVALID_PATHS_ERROR))
      // Handle error
    if (err && (err instanceof AutoIngestTool.EMPTY_FILE_ERROR))
      // Handle error

    console.log(err);
  }
);

IMPORTANT :

• You can have an INVALID_PARAMETERS_ERROR or INVALID_PATHS_ERROR when there is an issue with the parameters or paths JSON.
• If you try to download a report that have not been generated yet by Apple, you will receive an EMPTY_FILE_ERROR because the module have downloaded an empty file. This empty file will be removed automatically.

If there is no error, the callback will return an updated paths JSON object.

// updatedPaths
{
  archive: "/path/to/archive.txt.gz",
  report: "/path/to/extracted/archive.txt",
  json_report: "/path/to/transformed/archive.json"
}

Finally, you can open and parse the created JSON file and process it.

Report Formats

Sales Report

[
	{
    	"Provider": "APPLE",
    	"ProviderCountry": "US",
    	"SKU": "00000000",
    	"Developer": "ME",
    	"Title": "The Applicationssssss",
    	"Version": "7.1.2",
    	"ProductTypeIdentifier": "7T",
    	"Units": 11.00,
    	"DeveloperProceeds": 0.00,
    	"BeginDate": "03/13/2014",
    	"EndDate": "03/13/2014",
    	"CustomerCurrency": "JPY",
    	"CountryCode": "JP",
    	"CurrencyofProceeds": "JPY",
    	"AppleIdentifier": "111111111",
    	"CustomerPrice": 0.00,
    	"PromoCode": null,
    	"ParentIdentifier": null,
    	"Subscription": null,
    	"Period": null,
    	"Category": "Music"
	}
]

Newsstand Report

[
	{
    	"Provider": "APPLE",
        "ProviderCountry": "US",
        "SKU": "00000000",
        "Developer": "ME",
        "Title": "Something",
        "Version": "1.2.3",
        "ProductTypeIdentifier": "1E",
        "Units": 1.00,
        "DeveloperProceeds": 1.00,
        "CustomerCurrency": "JPY",
        "CountryCode": "JP",
        "CurrencyofProceeds": "JPY",
        "AppleIdentifier": "11111111",
        "CustomerPrice": 1.00,
        "PromoCode": null,
        "ParentIdentifier": null,
        "Subscription": null,
        "Period": null,
        "DownloadDate": null,
        "CustomerIdentifier": null,
        "ReportDate": null,
        "SalesReturn": "S",
        "Category": "Here"
    }
]

Opt-in Report

[
	{
    	"FirstName": "Oula",
        "LastName": "Hop",
        "EmailAddress": "oula.hop@splash.titi",
        "PostalCode": "22312334",
        "AppleIdentifier": "923843",
        "ReportStartDate": "10/10/2000",
        "ReportEndDate": "10/10/2001"
    }
]

Financial Report

[
    {
        "StartDate": "12/27/2015",
        "End Date": "01/30/2016",
        "UPC": null,
        "ISRC_ISBN": null,
        "VendorIdentifier": "APP001",
        "Quantity": 295,
        "PartnerShare": 2.10,
        "ExtendedPartnerShare": 619.50,
        "PartnerShareCurrency": "USD",
        "SalesorReturn": "S",
        "AppleIdentifier": "88776655",
        "Artist_Show_Developer_Author": "Developer name",
        "Title": "App Name",
        "Label_Studio_Network_Developer_Publisher": null,
        "Grid": null,
        "ProductTypeIdentifier": "1F",
        "ISAN_OtherIdentifier": null,
        "CountryOfSale": "US",
        "PreorderFlag": null,
        "PromoCode": null,
        "CustomerPrice": 2.99,
        "CustomerCurrency": "USD"
	},
	{
	    "TotalRows": 1,
	    "TotalUnits": 295,
	    "TotalAmount": 567
	}
]

Unit Testing (only if you want to contribute)

Actually you can only test sales report (daily, weekly, monthly and yearly) downloading. Why? We haven't created yet newsstand applications to get access to newsstand and opt-in reports.

So feel free to add tests for these reports.

How To

Install all dependencies and devDependencies

$ npm install

Run test using vows

$ vows tests/* --spec