README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# mixi2r

<!-- badges: start -->
[![R-CMD-check](https://github.com/statditto/mixi2r/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/statditto/mixi2r/actions/workflows/R-CMD-check.yaml)
[![Lifecycle: experimental](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
<!-- badges: end -->

**mixi2r** is an R wrapper for the [mixi2 Developer Platform API](https://developer.mixi.social/docs).

It communicates with the API using the standard **gRPC protocol** (`application/grpc+proto` over HTTP/2 with Protocol Buffers binary encoding) and OAuth 2.0 Client Credentials authentication.

Features:

- Create and retrieve posts (replies, quotes, media attachments, spoiler masks)
- Send chat (DM) messages
- Upload images and videos
- Retrieve and assign stamps
- Receive events via Webhook (Ed25519 signature verification included)

## Installation

```r
# Install from GitHub (not yet on CRAN)
# install.packages("pak")
pak::pak("statditto/mixi2r")
```

## Prerequisites

Create an application on the [mixi2 Developer Platform](https://developer.mixi.social/docs) and obtain the following credentials.

| Environment variable | Description |
|---|---|
| `MIXI2_CLIENT_ID` | OAuth2 client ID |
| `MIXI2_CLIENT_SECRET` | OAuth2 client secret |
| `MIXI2_TOKEN_URL` | Token endpoint URL |
| `MIXI2_API_ADDRESS` | API server address |
| `MIXI2_SIGNATURE_PUBLIC_KEY` | Base64-encoded Ed25519 public key (Webhook only) |

Store these in your `.Renviron` file:

```ini
MIXI2_CLIENT_ID=your_client_id
MIXI2_CLIENT_SECRET=your_client_secret
MIXI2_TOKEN_URL=https://application-auth.mixi.social/oauth2/token
MIXI2_API_ADDRESS=application-api.mixi.social
```

> **Security**: Never hard-code secrets in source code or commit them to version control.
> Use `.Renviron` or a secrets manager.

## Quick start

```r
library(mixi2r)

# Create a client (reads credentials from environment variables)
client <- mixi2_client()

# Create a post
post <- create_post(client, "Hello from R!")

# Reply to a post
create_post(client, "Thanks for your message!",
            in_reply_to_post_id = post$post_id)

# Quote a post
create_post(client, "Interesting post!",
            quoted_post_id = post$post_id)

# Post with a spoiler mask
create_post(client, "Movie spoiler content...",
            post_mask = list(
              mask_type = "POST_MASK_TYPE_SPOILER",
              caption   = "Spoiler warning"
            ))

# Get user information
users <- get_users(client, c("user_id_1", "user_id_2"))

# Get post information
posts <- get_posts(client, c("post_id_1"))

# Send a DM (requires a room_id from an incoming message event)
send_chat_message(client, room_id = "room_123", text = "Message received!")
```

## Media upload

```r
# Upload an image and attach it to a post
media_id <- upload_media(client, "photo.jpg")
create_post(client, "Check out this photo!", media_id_list = media_id)

# Upload a video
media_id <- upload_media(client, "video.mp4", media_type = "TYPE_VIDEO")
create_post(client, "Video post!", media_id_list = media_id)
```

## Stamps

```r
# Get available stamps
stamps <- get_stamps(client, language = "LANGUAGE_CODE_JP")
stamp_id <- stamps[[1]]$stamps[[1]]$stamp_id

# Assign a stamp to a post (only posts that mention your application)
add_stamp_to_post(client, post_id = "target_post_id", stamp_id = stamp_id)
```

## Webhook server

```r
library(mixi2r)

client <- mixi2_client()

my_handler <- function(event) {
  # Handle post creation events (mentions to your application)
  if (!is.null(event$post_created_event)) {
    ev   <- event$post_created_event
    post <- ev$post
    message("New post received: ", post$text)

    # Reply to the mention
    create_post(client, "Thanks for reaching out!",
                in_reply_to_post_id = post$post_id)
  }

  # Echo bot for DMs
  if (!is.null(event$chat_message_received_event)) {
    ev   <- event$chat_message_received_event
    msg  <- ev$message
    if (!is.null(msg$text)) {
      send_chat_message(client, room_id = msg$room_id, text = msg$text)
    }
  }
}

# Start the Webhook server (blocking)
start_webhook_server(
  handler    = my_handler,
  port       = 8080,
  public_key = Sys.getenv("MIXI2_SIGNATURE_PUBLIC_KEY")
)
```

## Function reference

| Function | RPC | Description |
|---|---|---|
| `mixi2_client()` | — | Create a client configuration object |
| `get_users(client, user_id_list)` | GetUsers | Retrieve user information |
| `get_posts(client, post_id_list)` | GetPosts | Retrieve post information |
| `create_post(client, text, ...)` | CreatePost | Create a post |
| `initiate_post_media_upload(client, ...)` | InitiatePostMediaUpload | Initiate a media upload |
| `get_post_media_status(client, media_id)` | GetPostMediaStatus | Check upload status |
| `upload_media(client, file_path, ...)` | (3-step wrapper) | Upload media (convenience function) |
| `send_chat_message(client, room_id, ...)` | SendChatMessage | Send a DM |
| `get_stamps(client, language)` | GetStamps | Get available stamps |
| `add_stamp_to_post(client, post_id, stamp_id)` | AddStampToPost | Assign a stamp to a post |
| `start_webhook_server(handler, port, ...)` | — | Start a Webhook event server |

## Related links

- [mixi2 Developer Platform documentation](https://developer.mixi.social/docs)
- [API reference](https://developer.mixi.social/docs/reference/api-document)
- [Protocol Buffers definitions (GitHub)](https://github.com/mixigroup/mixi2-api)
- [Official Go SDK (GitHub)](https://github.com/mixigroup/mixi2-application-sdk-go)

## License

MIT © statditto