schema {
  query: Query
}

"""
The Zoya API is a GraphQL API that provides access to a variety of data and
services related to Shariah compliant investing. The API is organized into
namespaces based on the subscription package you have purchased. For example,
users with the basicCompliance subscription package will have access to the
`basicCompliance` queries. Users with the advancedCompliance subscription
package will have access to the `advancedCompliance` queries in addition to
the `basicCompliance` ones.
"""
type Query {
  """
  This is the top-level namespace for all queries made available to users with
  the Basic Shariah Compliance subscription.
  """
  basicCompliance: BasicComplianceQuery!
  """
  This is the top-level namespace for all queries made available to users with
  the Advanced Shariah Compliance subscription.
  """
  advancedCompliance: AdvancedComplianceQuery!
  """
  The top-level namespace for zakat calculation queries. Contact
  support@zoya.finance for access.
  """
  zakat: ZakatQuery!
}

#####################
# MARK: Common Shapes
#####################

"""
An ISO8601 formatted datetime string.
"""
scalar AWSDateTime

"""
Possible Shariah compliance status for a given security or screen. Note that
financial screens will never have a result of `QUESTIONABLE`.
"""
enum ComplianceStatus {
  """
  The security is shariah compliant with a given screening methodology.
  """
  COMPLIANT

  """
  The security is not shariah compliant with a given screening methodology.
  """
  NON_COMPLIANT

  """
  The revenue sources of the associated entity are either from an area where
  there is a great deal of difference of opinion among scholars as to their
  permissibility or the financial reports do not contain enough information to
  be able to make a definitive judgement.
  """
  QUESTIONABLE

  """
  The security has no rating for the given screening methodology.
  """
  UNRATED
}

"""
Possible screening methodologies for evaluating Shariah compliance. While all
methodologies evaluate stocks based on impermissible income and exposure to
interest, the specific forumulas to calculate results vary. Currently, only the
AAOIFI methodology is supported, but we plan to add support for other
methodologies in the future.
"""
enum ScreeningMethodology {
  """
  The methodology currently used today in the Zoya Mobile App.
  """
  AAOIFI
}

########################
# MARK: Basic Compliance
########################

"""
Queries available for users with the basicCompliance subscription package. Users
with the advancedCompliance package also have permissions to these queries.
"""
type BasicComplianceQuery {
  """
  Retrieve the most recent Shariah compliance report for a given symbol based on
  the AAOIFI methodology. This endpoint is limited to US stocks only. If no
  report is found, this will return `null`.
  """
  report(
    """
    The symbol of the stock to retrieve a compliance report for (e.g., "AAPL" or "AMD").
    """
    symbol: String!
  ): BasicComplianceReport

  """
  Retrieve a list of Shariah compliance reports based on the AAOIFI methodology.
  Limited to US equities only.
  """
  reports(
    """
    Optional input for pagination and filtering options when listing reports.
    """
    input: BasicReportsInput
  ): BasicComplianceReportsPage!

  """
  Retrieves a list of funds and their compliance reports. Currently only covers
  US-based ETFs.
  """
  funds(
    """
    Optional input for pagination and filtering options when listing funds.
    Currently, it is recommended to omit this. It is for forward-compatibility
    of additional filtering capabilities and fund types.
    """
    input: BasicFundsInput
  ): BasicFundReportsPage!
}

type BasicFundReport {
  """
  The symbol/ticker used to identify the fund on exchanges.
  """
  symbol: String!

  """
  The name of the fund.
  """
  name: String!

  """
  The exchange on which the fund is traded. Nullable, as some funds may not
  have a specific exchange associated with them (e.g., some mutual funds).
  """
  exchange: String

  """
  The Shariah compliance status of the fund.
  """
  status: ComplianceStatus!

  """
  The latest date where fund holding information was available for the fund.
  Different funds publish updates at varying frequencies. Note that compliance
  report changes can occur even with no holdings information available due to
  compliance status changes of individual holdings.
  """
  holdingsAsOfDate: AWSDateTime!

  """
  NOTE: Only available for some customers. This value will be null by default.
  If you are interested in this field, please contact support.

  The portion of profits to be donated to charity for purification. Multiply
  this number by dividends received or capital gains realized to determine the
  amount to donate.
  """
  purificationRatio: Float

  """
  The date the compliance report was generated.
  """
  reportDate: AWSDateTime!
}

"""
A page of Shariah compliance reports for funds. The nextToken field can be used
to retrieve the next page of results via subsequent API calls.
"""
type BasicFundReportsPage {
  """
  List of Shariah compliance reports of funds.
  """
  items: [BasicFundReport!]!
  """
  The token to use to retrieve the next page of paginated results. This will be
  `null` if the last page has been reached and there are no more results.
  """
  nextToken: String
}

"""
Possible fund types that can be returned by the `basicCompliance/funds` query.
In practice, only ETF types are returned today. Mutual funds will be supported
in a future release.
"""
enum FundType {
  ETF
  MUTUAL_FUND
}

"""
Input for query/basicCompliance/funds field path. Currently, the API only
returns ETFs, so this input can be omitted and all funds will be returned.
The interface is structured for forward-compatibility with mutual funds and
filter additions in the future.
"""
input BasicFundsInput {
  """
  To retrieve the next page of results, pass the `nextToken` value from the
  previous API response as the `nextToken` parameter in the next API call.
  This field is optional.
  """
  nextToken: String
  """
  The maximum number of results to return per page. The default and maximum
  limit is 2000. This field is optional.
  """
  limit: Int
}

"""
Input for query/basicCompliance/reports field path. Supports filtering and pagination.
"""
input BasicReportsInput {
  """
  Filters will be applied to the list of reports returned by this API.
  Currently, you can use this to only fetch reports with a specific shariah
  compliance status. This field is optional.
  """
  filters: BasicReportFilters
  """
  To retrieve the next page of results, pass the `nextToken` value from the
  previous API response as the `nextToken` parameter in the next API call.
  This field is optional.
  """
  nextToken: String
  """
  The maximum number of results to return per page. The default is 100 and the
  maximum limit is 1000. This field is optional.
  """
  limit: Int
}

"""
Filters for limiting the list of Shariah compliance reports returned by the
`basicCompliance/reports` query.
"""
input BasicReportFilters {
  """
  Set to a compliance status to only return reports with that status.
  """
  status: ComplianceStatus
}

"""
The Shariah compliance report available for a given security.
"""
type BasicComplianceReport {
  """
  The symbol/ticker used to identify the stock on exchanges.
  """
  symbol: String!

  """
  The name of the company tied to the security.
  """
  name: String!

  """
  The exchange on which the stock is traded.
  """
  exchange: String!

  """
  The Shariah compliance status of the security.
  """
  status: ComplianceStatus!

  """
  The portion of profits to be donated to charity for purification. Multiply
  this number by dividends received or capital gains realized to determine the
  amount to donate.
  """
  purificationRatio: Float!

  """
  The date the compliance report was generated. Different companies publish
  financial reports at different times of the year, but for any given security,
  this will usually update once a quarter.
  """
  reportDate: AWSDateTime!
}

"""
A page of Shariah compliance reports. Use the `nextToken` field to retrieve the
next page of results via subsequent API calls.
"""
type BasicComplianceReportsPage {
  """
  List of Shariah compliance reports.
  """
  items: [BasicComplianceReport!]!
  """
  The token to use to retrieve the next page of paginated results. This will be
  `null` if the last page has been reached and there are no more results.
  """
  nextToken: String
}

###########################
# MARK: Advanced Compliance
###########################

"""
Queries available for users with the advancedCompliance subscription package.
"""
type AdvancedComplianceQuery {
  """
  Retrieve the most recent advanced Shariah compliance report for a given symbol
  or FIGI identifier based on the given methodology. If the identifier is not
  recognized or no report is found, this will return `null`.
  """
  report(
    """
    The input for retrieving a detailed compliance report for a given identifier
    and methodology. Both the methodolgy and some identifier (either `symbol` or
    `figi`) must be provided. If both are provided, `figi` will be used. An
    error will be thrown if neither are provided.

    Different fields are returned depending on the screening methodology used.
    The `AdvancedComplianceReport` interface is the base type that contains all
    fields in common across different methodologies. GraphQL fragment queries
    can be used to retrieve fields unique to a specific methdology.
    """
    input: AdvancedReportInput!
  ): AdvancedComplianceReport

  """
  Retrieve a list of advanced Shariah compliance reports for a given region and
  methodology.
  """
  reports(
    """
    The input for querying for a list of detailed compliance reports under the
    advancedCompliance API package. The `methodology` and `region` fields must
    be provided. The `filters` field is optional.

    This API is paginated. To retrieve the next page of results, pass the
    `nextToken` value from the previous API response as the `nextToken` parameter.
    When the last page of results is reached, the `nextToken` field will be `null`.
    """
    input: AdvancedReportsInput!
  ): AdvancedComplianceReportsPage!

  """
  Retrieve the list of supported regions/markets that have compliance reports
  available. These will always be ISO 3166-1 alpha-2 country codes (e.g. "US").
  """
  regions: [String!]!

  """
  Retrieve a list of stocks from MENA regions that are considered to be shariah
  compliant. The sandbox environment will just return a limited subset instead of mock data for this query.
  """
  menaScreens: [MENAScreens!]

  externalScreens: [MENAScreens!]
    @deprecated(reason: "Use menaScreens instead.")
}

type MENAScreens {
  """
  The symbol for the ticker without any exchange suffix included. Note that
  multiple distinct stocks may have identical symbols, but a pair of symbol and
  exchange will uniquely identify a listing.
  """
  rawSymbol: String!

  """
  The name of the company tied to the security.
  """
  name: String!

  """
  The exchange on which the stock is traded.
  """
  exchange: String!

  """
  The region in which the stock is traded. Will always be an ISO 3166-1 alpha-2
  country code (e.g. "KW" for Kuwait).
  """
  region: String!

  """
  The compliance status of the stock. Stocks in the MENA screened list
  will always be compliant.
  """
  status: ComplianceStatus!

  """
  The date the compliance report was last updated. Reports are updated based on
  company reports which are published at different times of the year.
  """
  reportDate: AWSDateTime!
}

"""
Input for querying for detailed compliance reports for a given identifier under
the advancedCompliance API package.

Either `symbol` or `figi` must be provided. If both are provided, `figi` will be
used. An error will be thrown if neither are provided.
"""
input AdvancedReportInput {
  """
  The symbol/ticker used to identify the stock on exchanges. For non-US symbols,
  the Bloomberg exchange suffix should be included (e.g., "TYT-LN" for
  "TYT" listing on the London Stock Exchange).

  Either symbol or figi must be provided. If both are provided, figi will be used.
  An error will be thrown if neither are provided.
  """
  symbol: String

  """
  The FIGI identifier for the entity whose compliance report is to be retrieved.

  Either figi or symbol must be provided. If both are provided, figi will be used.
  An error will be thrown if neither are provided.
  """
  figi: String

  """
  The screening methodology to use for Shariah compliance evaluation.
  """
  methodology: ScreeningMethodology!
}

"""
Input for querying for a list of detailed compliance reports under the
advancedCompliance API package.

This API is paginated. To retrieve the next page of results, pass the
`nextToken` value from the previous API response as the `nextToken` parameter.
When the last page of results is reached, the `nextToken` field will be `null`.
"""
input AdvancedReportsInput {
  """
  The region to list reports from (e.g. "US", "GB", "CA"). Available regions can
  be discovered by querying the API by advancedCompliance/regions.
  """
  region: String!

  """
  The screening methodology to use for Shariah compliance evaluation.
  """
  methodology: ScreeningMethodology!

  """
  Filters will be applied to the list of reports returned by this API.
  Currently, you can use this to only fetch reports with a specific shariah
  compliance status.
  """
  filters: AdvancedReportFilters

  """
  To retrieve the next page of results, pass the `nextToken` value from the
  previous API response as the `nextToken` parameter in the next API call.
  """
  nextToken: String

  """
  The maximum number of results to return per page. The default is 100 and the limit is 500.
  """
  limit: Int
}

"""
Filters for limiting the list of Shariah compliance reports returned by the
`advancedCompliance/reports` query.
"""
input AdvancedReportFilters {
  """
  Set to a compliance status to filter for reports with that status.
  """
  status: ComplianceStatus
}

"""
A page of advanced Shariah compliance reports. Use the `nextToken` field to
retrieve the next page of results via subsequent API calls.
"""
type AdvancedComplianceReportsPage {
  """
  A list of advanced Shariah compliance reports.
  """
  items: [AdvancedComplianceReport!]!
  """
  The token to use to retrieve the next page of paginated results. This will be
  `null` if the last page has been reached and there are no more results.
  """
  nextToken: String
}

"""
Base interface used across a variety of Shariah compliance reports. Other
reports may extend this interface with additional properties.
"""
interface AdvancedComplianceReport {
  """
  The symbol Zoya uses to uniquely identify a stock. Exchange specific suffixes
  will be used for international exchanges outside the US.
  """
  symbol: String!
  """
  The symbol for the ticker without any exchange suffix included. Note that
  multiple distinct stocks may have identical symbols.
  """
  rawSymbol: String!
  """
  The name of the entity associated with this report.
  """
  name: String!
  """
  The FIGI identifier for the entity associated with this report. This field may
  be `null` for some entities.
  """
  figi: String
  """
  The exchange on which the stock is traded.
  """
  exchange: String!
  """
  The overall Shariah compliance status of the stock or security.
  """
  status: ComplianceStatus!
  """
  The date the compliance report was last updated. Reports are updated based on
  company reports which are published at different times of the year.
  """
  reportDate: AWSDateTime!
  """
  The Shariah compliance of the revenue sources of the associated entity.
  """
  businessScreen: ComplianceStatus!
  """
  The Shariah compliance of financial ratios of the associated entity based on
  the screening methodology.
  """
  financialScreen: ComplianceStatus!
  """
  Percentage of revenue earned that is considered Shariah compliant.
  """
  compliantRevenue: Float!
  """
  Percentage of revenue earned that is considered not Shariah compliant.
  """
  nonCompliantRevenue: Float!
  """
  Percentage of revenue earned that is considered questionable with regards to
  Shariah compliance. This may be due to broad differences of opinions among
  scholars or due to limited details published by the company for a given
  revenue segment.
  """
  questionableRevenue: Float!
  """
  The portion of profits to be donated to charity for purification. Multiply
  this number by dividends received or capital gains realized to determine the
  amount to donate.
  """
  purificationRatio: Float!
}

"""
Report shape used for the AAOIFI methodology.
"""
type AAOIFIReport implements AdvancedComplianceReport {
  """
  The symbol Zoya uses to uniquely identify a stock. Exchange specific suffixes
  will be used for international exchanges outside the US.
  """
  symbol: String!
  """
  The symbol for the ticker without any exchange suffix included. Note that
  multiple distinct stocks may have identical symbols.
  """
  rawSymbol: String!
  """
  The name of the entity associated with this report.
  """
  name: String!
  """
  The FIGI identifier for the entity associated with this report. This field may
  be `null` for some entities.
  """
  figi: String
  """
  The exchange on which the stock is traded.
  """
  exchange: String!
  """
  The overall Shariah compliance status of the stock or security.
  """
  status: ComplianceStatus!
  """
  The date the compliance report was last updated. Reports are updated based on
  company reports which are published at different times of the year.
  """
  reportDate: AWSDateTime!
  """
  The Shariah compliance of the revenue sources of the associated entity.
  """
  businessScreen: ComplianceStatus!
  """
  The Shariah compliance of financial ratios of the associated entity based on
  the screening methodology.
  """
  financialScreen: ComplianceStatus!
  """
  Percentage of revenue earned that is considered Shariah compliant.
  """
  compliantRevenue: Float!
  """
  Percentage of revenue earned that is considered not Shariah compliant.
  """
  nonCompliantRevenue: Float!
  """
  Percentage of revenue earned that is considered questionable with regards to
  Shariah compliance. This may be due to broad differences of opinions among
  scholars or due to limited details published by the company for a given
  revenue segment.
  """
  questionableRevenue: Float!
  """
  The portion of profits to be donated to charity for purification. Multiply
  this number by dividends received or capital gains realized to determine the
  amount to donate.
  """
  purificationRatio: Float!
  """
  Ratio of interest-bearing debt relative to market capitalization.
  """
  debtToMarketCapRatio: Float!
  """
  Ratio of interest bearing securities relative to market capitalization.
  """
  securitiesToMarketCapRatio: Float!
}

#############
# MARK: Zakat
#############

"""
Queries available for users with the zakat subscription package. Users
"""
type ZakatQuery {
  calculate(holdings: [ZakatHolding!]!): ZakatCalculation!
}

"""
Enum of different strategies to use for calculating zakat on a holding.
Actively traded holdings get treated as cash while passive investments factor in
the percentage of shares owned relative to the current assets held by an entity
as the basis for determining the zakat liable amount.
"""
enum ZakatHoldingStrategy {
  """
  Should be used for holdings that are intended to be actively traded and held
  for less than 1 year. Active investments will be treated as cash for purposes
  of zakat calculation.
  """
  ACTIVE

  """
  Should be used for holdings that are intended to be held for more than 1 year.
  This approach factors in what percentage of a company you own and then looks
  at the proportional amount of current assets held by the company to determine
  the zakat liable amount. For ETFs and mutual funds, the calculation strategy
  is applied recursively over the holdings of the fund based on their weighted
  holdings.
  """
  PASSIVE
}

"""
Method used to calculate the zakatable amount and zakat due
"""
enum ZakatCalculationMethod {
  """
  Treat holding as cash.
  The zakat due is 2.5% of the asset market value.
  """
  TREAT_AS_CASH

  """
  The zakat liable amount is determined using a formula that considers the
  asset outstanding shares and total assets
  The zakat due is 2.5% of ((sharesHeld / outstandingShares) * currentAssets)
  """
  PASSIVE_INVESTMENT

  """
  Fallback of calculating the zakat on 30% of the asset market value
  The zakat due is 2.5% of 30% of the asset market value.
  """
  FALLBACK_30
}

"""
Input for zakat calculation of a holding
"""
input ZakatHolding {
  """
  The symbol of the asset to calculate zakat for (e.g., "AAPL" or "AMD").
  """
  symbol: String
  """
  The strategy to use for calculating zakat on this holding. ACTIVE should be
  used for holdings that are intended to be actively traded and held for less
  than 1 year. PASSIVE should be used for holdings that are intended to be held
  for more than 1 year.
  """
  strategy: ZakatHoldingStrategy!
  """
  The number of shares or units of the asset held.
  """
  quantity: Float!
  """
  The unit price of the asset in the currency it is denominated in.
  """
  unitPrice: Float!
}

"""
The result of a zakat calculation for a single holding.
"""
type ZakatHoldingCalculation {
  """
  The symbol of the asset that was used for the zakat calculation.
  """
  symbol: String
  """
  The strategy used for calculating zakat on this holding.
  """
  strategy: ZakatHoldingStrategy!
  """
  The ISO 4217 currency code for the asset.
  """
  currency: String!
  """
  The market value of the holding (quantity * unitPrice)
  """
  marketValue: Float!
  """
  The zakat liable amount for this holding. This will differ based on the zakat
  calculation strategy used for the holding.
  """
  zakatLiableAmount: Float!
  """
  The zakat due for this holding. This will be 2.5% of the zakat liable amount.
  """
  zakatDue: Float!
  """
  The zakat calculation method ultimately used for this holding. Some assets
  have special handling rules, such as how precious metals spot funds are
  treated as cash for zakat purposes. In cases where reliable data is not
  available for outstanding shares or current assets, a fallback method of
  taking 30% of the market value as the zakat liable amount is used.
  """
  calculationMethod: ZakatCalculationMethod!
}

"""
The result of a zakat calculation for a set of holdings.
"""
type ZakatCalculation {
  """
  The sum of the calculated zakat liable amount for all holdings. The zakat due
  will be 2.5% of this number.
  """
  zakatLiableAmount: Float!
  """
  The total zakat due for all given holdings.
  """
  zakatDue: Float!
  """
  The ISO 4217 currency code for the zakat due amount. If holdings with mixed
  currencies were given as input, the results will be in USD.
  """
  currency: String!
  """
  The individual zakat calculations for each holding given as input.
  """
  holdings: [ZakatHoldingCalculation!]!
}