openapi: 3.1.0
info:
  title: ShardDog API
  description: |
    ShardDog API for creating and claiming NFT linkdrops on NEAR Protocol.
    
    ## Authentication
    Most endpoints are public. Channel creation requires payment via NEAR or PingPay.
    
    ## Base URLs
    - Production: `https://shard.dog`
    - Staging: `https://sit.shard.dog`
  version: 4.0.0
  contact:
    name: ShardDog
    url: https://shard.dog

servers:
  - url: https://sit.shard.dog
    description: API Server

paths:
  /api/channels/list:
    get:
      operationId: listChannels
      summary: List channels by owner
      description: Get all channels owned by a specific NEAR wallet
      parameters:
        - name: owner
          in: query
          required: true
          schema:
            type: string
          description: NEAR wallet address of channel owner
      responses:
        '200':
          description: List of channels
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Channel'

  /api/channels/{slug}:
    get:
      operationId: getChannel
      summary: Get channel by slug
      description: Retrieve channel details including metadata and claim info
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
          description: Channel slug (e.g., "my-collection")
      responses:
        '200':
          description: Channel details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Channel'
        '404':
          description: Channel not found

  /api/getFeed:
    get:
      operationId: getUserFeed
      summary: Get user's NFT collection
      description: Retrieve all NFTs claimed by a wallet
      parameters:
        - name: wallet
          in: query
          required: true
          schema:
            type: string
          description: NEAR wallet address
      responses:
        '200':
          description: User's NFT feed
          content:
            application/json:
              schema:
                type: object
                properties:
                  feed:
                    type: array
                    items:
                      $ref: '#/components/schemas/FeedItem'

  /api/users/{wallet}/stats:
    get:
      operationId: getUserStats
      summary: Get user statistics
      description: Get claim statistics for a wallet
      parameters:
        - name: wallet
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: User stats
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserStats'

  /api/check-slugs/mint:
    post:
      operationId: mintNft
      summary: Mint/claim an NFT
      description: Mint an NFT from a channel to a wallet. This is the main claim endpoint.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - accountId
                - seriesId
              properties:
                accountId:
                  type: string
                  description: NEAR wallet to receive the NFT
                seriesId:
                  type: string
                  description: Channel series ID
                slug:
                  type: string
                  description: Channel slug (alternative to seriesId)
      responses:
        '200':
          description: Mint successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  mintResponse:
                    type: object
                    properties:
                      statusCode:
                        type: integer
                      body:
                        type: string
        '400':
          description: Invalid request or already claimed
        '403':
          description: Invite required

  /api/nft/claim-status/check:
    get:
      operationId: checkClaimStatus
      summary: Check claim status
      description: Check if a wallet has already claimed from a channel
      parameters:
        - name: slug
          in: query
          required: true
          schema:
            type: string
        - name: wallet
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Claim status
          content:
            application/json:
              schema:
                type: object
                properties:
                  claimed:
                    type: boolean
                  claimDate:
                    type: string
                    format: date-time

  /api/pingpay/create-session:
    post:
      operationId: createPaymentSession
      summary: Create channel with PingPay
      description: |
        Create a new channel by paying with any supported token via PingPay/NEAR Intents.
        Cost: 10 NEAR (payable in any token - will be swapped automatically)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - title
                - imageUrl
                - wallet
              properties:
                title:
                  type: string
                  description: Channel name
                description:
                  type: string
                  description: Channel description
                imageUrl:
                  type: string
                  description: IPFS or HTTP URL for NFT image
                wallet:
                  type: string
                  description: Owner's NEAR wallet
      responses:
        '200':
          description: Payment session created
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionUrl:
                    type: string
                    description: Redirect URL to complete payment
                  orderId:
                    type: string
                    description: Order ID for tracking

components:
  schemas:
    Channel:
      type: object
      properties:
        id:
          type: string
        slug:
          type: string
        name:
          type: string
        owner:
          type: string
          description: NEAR wallet address
        description:
          type: string
        imageUrl:
          type: string
        inviteOnly:
          type: boolean
        createdAt:
          type: string
          format: date-time
        totalClaims:
          type: integer

    FeedItem:
      type: object
      properties:
        imageUrl:
          type: string
        title:
          type: string
        description:
          type: string
        date:
          type: string
          format: date-time
        slug:
          type: string
        wallet:
          type: string
        series_id:
          type: string

    UserStats:
      type: object
      properties:
        totalMemories:
          type: integer
        thisYearMemories:
          type: integer