autoingesttool

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.

Property	Type	Description	Possible values	Required
username	string	iTunes Connect account username which have access to the Sales and Trends reports.	-	YES
password	string	iTunes Connect account password.	-	YES
vendor_number	string	iTunes Connect vendor number.	-	YES
report_type	string	Report type. Learn more	Sales, Newsstand	YES
report_subtype	string	Report subtype. Learn more	Summary, Detailed, Opt-In	YES
date_type	string	Date type. Learn more	Daily, Weekly, Monthly, Yearly	YES
report_date	string	Date of the report. Learn more	YYYYMMDD (Daily and Weekly), YYYYMM (Monthly), YYYY (Yearly)	NO

// 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.

Property	Type	Description	Possible values	Required
username	string	iTunes Connect account username which have access to the Sales and Trends reports.	-	YES
password	string	iTunes Connect account password.	-	YES
vendor_number	string	iTunes Connect vendor number including 2 leading zeroes.	-	YES
report_type	string	Report type. Learn more	DRR	YES
region_code	string	Two-character code of country of report to download. For a list of region codes, see here.	-	YES
fiscal_year	number	Four-digit year of report to download. Year is specific to Apple’s fiscal calendar	-	YES
fiscal_period	number	Two-digit period in fiscal year of report to download (01-12). Period is specific to Apple’s fiscal calendar.	-	YES

// 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": "[e-mail]",
        "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