schema.graphql

"""
A user of web3.storage.
"""
type User {
  name: String!
  picture: String
  email: String!
  issuer: String! @unique

  """
  GitHub user handle, may be null if user logged in via email.
  """
  github: String

  """
  Cryptographic public address of the Magic User.
  """
  publicAddress: String!

  """
  User authentification keys.
  """
  keys: [AuthToken!]! @relation

  """
  Creation date.
  """
  created: Time!

  """
  Used storage in bytes.
  """
  usedStorage: Long
}

"""
API authentication tokens.
"""
type AuthToken {
  """
  User assigned name.
  """
  name: String!

  """
  Secret that corresponds to this token.
  """
  secret: String!

  """
  Uploads made using this token.
  """
  uploads: [Upload!]! @relation

  """
  User this token belongs to.
  """
  user: User! @relation

  """
  Creation date.
  """
  created: Time!

  """
  Deletion date.
  """
  deleted: Time
}

"""
Details of the root of a file/directory stored on web3.storage.
"""
type Content {
  """
  Root CID for this content.
  """
  cid: String! @unique

  """
  IPFS nodes pinning this content.
  """
  pins: [Pin]! @relation

  """
  Content for deals is aggregated together. Each aggregation has many entries.
  These are the entries that this content appears in.
  """
  aggregateEntries: [AggregateEntry!]! @relation

  """
  Size of the DAG in bytes. Set if known on upload or for partials is set when
  content is fully pinned in at least one location.
  """
  dagSize: Long

  """
  Creation date.
  """
  created: Time!
}

"""
Information for piece of content pinned in IPFS.
"""
type Pin {
  """
  The content being pinned.
  """
  content: Content! @relation

  """
  Identifier for the service that is pinning this pin.
  """
  location: PinLocation! @relation

  """
  Pinning status at this location.
  """
  status: PinStatus!

  """
  Last time the status was updated.
  """
  updated: Time!

  """
  Creation date.
  """
  created: Time!
}

"""
Location of a pin.
"""
type PinLocation {
  """
  Known pins at this location.
  """
  pins: [Pin]! @relation

  """
  Libp2p peer ID of the node pinning this pin.
  """
  peerId: String! @unique

  """
  Name of the peer pinning this pin.
  """
  peerName: String

  """
  Geographic region this node resides in.
  """
  region: String
}

enum PinStatus {
  Undefined
  ClusterError
  PinError
  UnpinError
  Pinned
  Pinning
  Unpinning
  Unpinned
  Remote
  PinQueued
  UnpinQueued
  Sharded
}

"""
Tracks requests to replicate content to more nodes.
"""
type PinRequest {
  """
  Root CID to Pin.
  """
  cid: String! @unique

  """
  The content that we want replicated.
  """
  content: Content! @relation

  """
  Number of times we have tried to pin this CID
  """
  attempts: Int!

  """
  Last time attempts was updated
  """
  updated: Time!

  """
  When the PinRequest was created
  """
  created: Time!
}

"""
A request to keep a Pin in sync with the nodes that are pinning it.
"""
type PinSyncRequest {
  """
  The pin to keep in sync.
  """
  pin: Pin! @relation

  """
  When the PinSyncRequest was created.
  """
  created: Time!
}

"""
Details of the backups created for an upload.
"""
type Backup {
  """
  Upload that originated the backup
  """
  upload: Upload! @relation

  """
  Backup url.
  """
  url: String!

  """
  Creation date.
  """
  created: Time!

  """
  Deletion date.
  """
  deleted: Time
}

"""
An upload created by a user.
"""
type Upload {
  """
  User that uploaded this content.
  """
  user: User! @relation

  """
  User authentication token that was used to upload this content.
  Note: nullable, because the user may have used a Magic.link token.
  """
  authToken: AuthToken @relation

  """
  User provided name for this upload.
  """
  name: String

  """
  Type of received upload data.
  """
  type: UploadType!

  """
  The root of the uploaded content.
  """
  content: Content! @relation

  """
  Creation date.
  """
  created: Time!

  """
  Deletion date.
  """
  deleted: Time
}

"""
Type of received upload data.
"""
enum UploadType {
  """
  A CAR file upload.
  """
  Car
  """
  Files uploaded and converted into a CAR file.
  """
  Upload
  """
  A raw blob upload in the request body.
  """
  Blob
  """
  A multi file upload using a multipart request.
  """
  Multipart
}

"""
An aggregate of content for inclusion in a Filecoin deal.
"""
type Aggregate {
  """
  CID of the root of the aggregate data.
  """
  dataCid: String! @unique

  """
  Piece CID.
  """
  pieceCid: String!

  """
  Deals this aggregation can be found in.
  """
  deals: [Deal!]! @relation

  """
  Entries included in this aggregate.
  """
  entries: [AggregateEntry!]! @relation

  """
  Creation date.
  """
  created: Time!
}

"""
Information about an entry included in an aggregate.
"""
type AggregateEntry {
  """
  The content this entry is for.
  """
  content: Content! @relation

  """
  The aggregate this entry resides in.
  """
  aggregate: Aggregate! @relation

  """
  Selector for extracting stored data from the aggregate data root.
  """
  dataModelSelector: String
}

"""
Filecoin deal for an aggregation of content.
"""
type Deal {

  """
  Content aggregate for this deal.
  """
  aggregate: Aggregate! @relation

  """
  ID of storage provider this deal was made with.
  """
  storageProvider: String!

  """
  Identifier for the deal stored on chain.
  """
  dealId: Long! @unique

  """
  Time when deal will be active.
  """
  activation: Time

  """
  Time when deal has expired and will renew.
  """
  renewal: Time

  """
  Current deal status.
  """
  status: DealStatus!

  """
  Human readable reason for the current status.
  """
  statusReason: String

  """
  Creation date.
  """
  created: Time!

  """
  Last time this deal was updated.
  """
  updated: Time!
}

enum DealStatus {
  Queued
  Published
  Active
  Terminated
}

enum SortDirection {
  Asc
  Desc
}

enum UploadListSortBy {
  Date,
  Name
}

type Metric {
  """
  Unique key identifying the metric.
  """
  key: String! @unique
  """
  Current value for the metric, see updated property for last calculation date.
  """
  value: Long!
  """
  Last time this metric was updated.
  """
  updated: Time!
}

type Query {
  """
  Find all uploads created after a given date. Note: this INCLUDES deleted uploads.
  """
  findUploadsCreatedAfter(since: Time!): [Upload!]! @resolver(paginated: true)
  findUploadsByUser(where: FindUploadsByUserInput!, sortBy: UploadListSortBy, sortOrder: SortDirection): [Upload!]! @resolver(paginated: true)
  findContentByCid(cid: String!): Content @resolver
  findContentByCreated(from: Time!, to: Time): [Content!]! @resolver(paginated: true)
  findUserByIssuer(issuer: String!): User @resolver
  findAuthTokensByUser(user: ID!): [AuthToken!]! @resolver(paginated: true)
  """
  Verify the User with the passed issuer owns the AuthToken with the passed secret.
  """
  verifyAuthToken(issuer: String!, secret: String!): AuthToken @resolver
  findPinsByStatus(status: PinStatus!): [Pin!]! @resolver(paginated: true)
  findPinsByStatusAndCreated(status: PinStatus!, from: Time!, to: Time): [Pin!]! @resolver(paginated: true)
  findAllPinRequests: [PinRequest!]! @resolver(paginated: true)
  findUsersByCreated(from: Time!, to: Time): [User!]! @resolver(paginated: true)
  countUsers(from: Time!, to: Time): [Long]! @resolver(paginated: true)
  countUploads(from: Time!, to: Time): [Long]! @resolver(paginated: true)
  countContent(from: Time!, to: Time): [Long]! @resolver(paginated: true)
  countPins(from: Time!, to: Time): [Long]! @resolver(paginated: true)
  countPinsByStatus(status: PinStatus!, from: Time!, to: Time): [Long]! @resolver(paginated: true)
  sumContentDagSize(from: Time!, to: Time): [Long]! @resolver(paginated: true)
  sumPinDagSize(from: Time!, to: Time): [Long]! @resolver(paginated: true)
  findMetricByKey(key: String!): Metric @resolver
  findPinSyncRequests(from: Time, to: Time): [PinSyncRequest!]! @resolver(paginated: true)
}

type Mutation {
  createOrUpdateUser(data: CreateOrUpdateUserInput!): User! @resolver
  createAuthToken(data: CreateAuthTokenInput): AuthToken! @resolver
  createUpload(data: CreateUploadInput!): Upload! @resolver
  deleteAuthToken(user: ID!, authToken: ID!): AuthToken! @resolver
  deleteUserUpload(user: ID!, cid: String!): Upload! @resolver
  renameUserUpload(user: ID!, cid: String!, name: String!): Upload! @resolver
  deleteUploadByUserAndContent(user: ID!, content: ID!): Upload! @resolver
  createAggregate(data: CreateAggregateInput!): Aggregate! @resolver
  """
  Adds new entries to the aggregate, existing entries are ignored.
  """
  addAggregateEntries(dataCid: String!, entries: [AggregateEntryInput!]!): Aggregate! @resolver
  createOrUpdateDeal(data: CreateOrUpdateDealInput!): Deal! @resolver
  """
  Creates a new pin object (and location) or updates an existing pin object.
  """
  createOrUpdatePin(data: CreateOrUpdatePinInput): Pin! @resolver
  updateContentDagSize(content: ID!, dagSize: Long!): Content! @resolver
  createPinRequest(cid: String!): PinRequest! @resolver
  deletePinRequests(requests: [ID!]!): [PinRequest!]! @resolver
  incrementPinRequestAttempts(pinRequest: ID!): PinRequest! @resolver
  incrementUserUsedStorage(user: ID!, amount: Long!): User! @resolver
  createOrUpdateMetric(data: CreateOrUpdateMetricInput!): Metric! @resolver
  updatePins(pins: [UpdatePinInput!]!): [Pin!]! @resolver
  createPinSyncRequests(pins: [ID!]!): [PinSyncRequest!]! @resolver
  deletePinSyncRequests(requests: [ID!]!): [PinSyncRequest!]! @resolver
}

input CreateAggregateInput {
  dataCid: String!
  pieceCid: String!
}

input AggregateEntryInput {
  cid: String!
  dataModelSelector: String
  dagSize: Long
}

input CreateOrUpdateDealInput {
  """
  CID of the aggregate included in this deal. Required for create, ignored for update.
  """
  dataCid: String
  storageProvider: String
  dealId: Long!
  activation: Time
  renewal: Time
  status: DealStatus!
  statusReason: String
}

input FindUploadsByUserInput {
  user: ID!
  createdBefore: Time!
}

input CreateOrUpdateUserInput {
  name: String!
  picture: String
  email: String!
  issuer: String!
  github: String
  publicAddress: String!
}

input CreateAuthTokenInput {
  user: ID!
  name: String!
  secret: String!
}

input CreateUploadInput {
  user: ID!
  authToken: ID
  cid: String!
  type: UploadType!
  name: String
  backupUrls: [String]!
  dagSize: Long
  chunkSize: Long # decremented, unused
  pins: [PinInput!]!
}

input PinInput {
  status: PinStatus!
  location: PinLocationInput!
}

input PinLocationInput {
  peerId: String!,
  peerName: String
  region: String
}

input CreateOrUpdatePinInput {
  content: ID!
  status: PinStatus!
  location: PinLocationInput!
}

input CreateOrUpdateMetricInput {
  key: String!
  value: Long!
  updated: Time
}

input UpdatePinInput {
  pin: ID!
  status: PinStatus!
}