node package manager
Easy sharing. Manage teams and permissions with one click. Create a free org »

autoingesttool

autoingesttool

Travis Build on branch master NPM total downloads per month David dependencies David dev dependencies CodeClimate

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": "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