osfapi

package
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 18, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package osfapi implements the OSF API v2 HTTP client used by the CLI.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError 

type APIError struct {
	StatusCode int
	Method     string
	Path       string
	Title      string
	Detail     string
}

APIError preserves OSF status and error detail fields.

func (*APIError) Error 

func (e *APIError) Error() string

Error returns a human-readable summary of the OSF API error.

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client is an HTTP client for the OSF API v2 JSON:API surface. It handles authentication, pagination, and JSON deserialization.

func New 

func New(baseURL string, opts ...Option) (*Client, error)

New creates a Client that communicates with the given OSF API base URL. If baseURL is empty, the default production URL (https://api.osf.io/v2/) is used. Returns an error if the URL cannot be parsed.

func (*Client) CreateFolder 

func (c *Client) CreateFolder(ctx context.Context, providerURL, folderName string) error

CreateFolder creates a folder via WaterButler.

func (*Client) CreateNode 

func (c *Client) CreateNode(ctx context.Context, title, category, description string) (Node, error)

CreateNode creates an OSF node with the supplied title, category, and description.

func (*Client) CreateRegistration 

func (c *Client) CreateRegistration(ctx context.Context, nodeID string, request RegistrationRequest) (Node, error)

CreateRegistration creates a draft registration for a node.

func (*Client) CurrentUser 

func (c *Client) CurrentUser(ctx context.Context) (User, error)

CurrentUser returns the authenticated user's profile information. Requires a valid bearer token; returns MissingTokenError otherwise.

func (*Client) DeleteFile 

func (c *Client) DeleteFile(ctx context.Context, providerURL, fileName string) error

DeleteFile deletes a file via WaterButler.

func (*Client) DeleteNode 

func (c *Client) DeleteNode(ctx context.Context, id string) error

DeleteNode deletes an OSF node by ID.

func (*Client) GetNode 

func (c *Client) GetNode(ctx context.Context, id string) (Node, error)

GetNode returns a single node (project or component) by its OSF GUID.

func (*Client) GetNodeFilesProvider 

func (c *Client) GetNodeFilesProvider(ctx context.Context, nodeID string) (string, error)

GetNodeFilesProvider gets the files provider URL for a node's OSF Storage. Returns the provider URL for use with WaterButler operations.

func (*Client) GetStorageFile 

func (c *Client) GetStorageFile(ctx context.Context, id string) (StorageFile, error)

GetStorageFile returns a single storage file or folder metadata record by its OSF GUID.

func (*Client) GetUser 

func (c *Client) GetUser(ctx context.Context, id string) (User, error)

GetUser returns a user profile by OSF user ID.

func (*Client) ListCurrentUserProjects 

func (c *Client) ListCurrentUserProjects(ctx context.Context) ([]Node, error)

ListCurrentUserProjects returns all project-category nodes owned by the current user. Automatically follows pagination links. Requires a bearer token.

func (*Client) ListFileVersions 

func (c *Client) ListFileVersions(ctx context.Context, fileID string) ([]FileVersion, error)

ListFileVersions loads all versions for a file.

func (*Client) ListNodeAddons 

func (c *Client) ListNodeAddons(ctx context.Context, id string) ([]Node, error)

ListNodeAddons lists all storage add-ons configured for a node.

func (*Client) ListNodeChildren 

func (c *Client) ListNodeChildren(ctx context.Context, id string) ([]Node, error)

ListNodeChildren returns all immediate child components of the specified node. Automatically follows pagination links.

func (*Client) ListNodeComments 

func (c *Client) ListNodeComments(ctx context.Context, id string) ([]Node, error)

ListNodeComments loads comments linked to a node.

func (*Client) ListNodeContributors 

func (c *Client) ListNodeContributors(ctx context.Context, id string) ([]Contributor, error)

ListNodeContributors returns all contributors for the specified node. Automatically follows pagination links.

func (*Client) ListNodeIdentifiers 

func (c *Client) ListNodeIdentifiers(ctx context.Context, id string) ([]Node, error)

ListNodeIdentifiers loads identifiers linked to a node.

func (*Client) ListNodeLogs 

func (c *Client) ListNodeLogs(ctx context.Context, id string) ([]Node, error)

ListNodeLogs loads audit log entries linked to a node.

func (*Client) ListNodeRegistrations 

func (c *Client) ListNodeRegistrations(ctx context.Context, id string) ([]Node, error)

ListNodeRegistrations loads registrations linked to a node.

func (*Client) ListPreprints 

func (c *Client) ListPreprints(ctx context.Context, provider string, limit ...int) ([]Node, error)

ListPreprints loads preprints visible to the current request context.

func (*Client) ListStorageFiles 

func (c *Client) ListStorageFiles(ctx context.Context, nodeID string, segments ...string) ([]StorageFile, error)

ListStorageFiles returns all files and folders from a node's OSF Storage provider. Additional path segments can be provided to navigate into subfolders. Automatically follows pagination links.

func (*Client) ListWikiPages 

func (c *Client) ListWikiPages(ctx context.Context, id string) ([]Node, error)

ListWikiPages loads wiki pages linked to a node.

func (*Client) OpenDownload 

func (c *Client) OpenDownload(ctx context.Context, downloadURL string) (io.ReadCloser, error)

OpenDownload opens the given download URL and returns the response body. The caller is responsible for closing the returned io.ReadCloser.

func (*Client) SearchOSF 

func (c *Client) SearchOSF(ctx context.Context, query string, limit ...int) ([]SearchResult, error)

SearchOSF performs a search across OSF content.

func (*Client) UpdateNode 

func (c *Client) UpdateNode(ctx context.Context, id, title, description string) (Node, error)

UpdateNode updates title and description metadata for an OSF node.

func (*Client) UploadFile 

func (c *Client) UploadFile(ctx context.Context, providerURL, fileName string, content io.Reader, conflict string) error

UploadFile uploads content to a storage provider via WaterButler. The providerURL is typically obtained from GET /v2/nodes/{id}/files/osfstorage/ and looks like "https://files.osf.io/v1/providers/osfstorage/..."

type Contributor 

type Contributor struct {
	ID         string                `json:"id"`
	Type       string                `json:"type"`
	Attributes ContributorAttributes `json:"attributes"`
	Links      Links                 `json:"links"`
}

Contributor models a node contributor entry.

type ContributorAttributes 

type ContributorAttributes struct {
	FullName      string `json:"full_name"`
	Bibliographic bool   `json:"bibliographic"`
	Permission    string `json:"permission,omitempty"`
}

ContributorAttributes carries contributor display and permission metadata.

type FileVersion 

type FileVersion struct {
	ID         string                `json:"id"`
	Type       string                `json:"type"`
	Attributes FileVersionAttributes `json:"attributes"`
	Links      Links                 `json:"links"`
}

FileVersion represents a version of an OSF storage file.

type FileVersionAttributes 

type FileVersionAttributes struct {
	Size         int64     `json:"size,omitempty"`
	DateCreated  time.Time `json:"date_created,omitempty"`
	DateModified time.Time `json:"date_modified,omitempty"`
}

FileVersionAttributes carries size and timestamp metadata for a file version. 

type Links struct {
	Self     string `json:"self,omitempty"`
	Next     string `json:"next,omitempty"`
	Prev     string `json:"prev,omitempty"`
	Related  string `json:"related,omitempty"`
	Download string `json:"download,omitempty"`
}

Links carries the JSON:API link set used by OSF responses.

type Node 

type Node struct {
	ID         string         `json:"id"`
	Type       string         `json:"type"`
	Attributes NodeAttributes `json:"attributes"`
	Links      Links          `json:"links"`
}

Node models OSF projects and components.

type NodeAttributes 

type NodeAttributes struct {
	Title       string `json:"title"`
	Description string `json:"description,omitempty"`
	Category    string `json:"category,omitempty"`
}

NodeAttributes carries display and category fields for OSF nodes.

type Option 

type Option func(*Client)

Option configures a Client using the functional options pattern.

func WithBearerToken 

func WithBearerToken(token string) Option

WithBearerToken sets the Authorization header for API requests.

func WithCredentials 

func WithCredentials(credentials auth.Credentials) Option

WithCredentials sets the OSF credential mode for API requests.

func WithHTTPClient 

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient sets the HTTP client used for API requests. If nil, a client with the default OSF timeout is used.

func WithUsernamePassword 

func WithUsernamePassword(username, password string) Option

WithUsernamePassword sets HTTP Basic request signing credentials.

type RegistrationRequest 

type RegistrationRequest struct {
	SchemaID    string `json:"schemaId"`
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
}

RegistrationRequest describes the draft registration fields submitted for a node.

type SearchResult 

type SearchResult struct {
	ID          string `json:"id"`
	Type        string `json:"type"`
	Title       string `json:"title,omitempty"`
	Description string `json:"description,omitempty"`
	Category    string `json:"category,omitempty"`
	URL         string `json:"url,omitempty"`
}

SearchResult models one OSF search result across supported resource types.

type StorageFile 

type StorageFile struct {
	ID         string                `json:"id"`
	Type       string                `json:"type"`
	Attributes StorageFileAttributes `json:"attributes"`
	Links      Links                 `json:"links"`
}

StorageFile models OSF Storage file and folder entries.

func (StorageFile) DownloadURL 

func (f StorageFile) DownloadURL() string

DownloadURL returns the file download URL when OSF provides one.

type StorageFileAttributes 

type StorageFileAttributes struct {
	Name string `json:"name"`
	Kind string `json:"kind"`
	Size int64  `json:"size,omitempty"`
}

StorageFileAttributes carries OSF Storage file metadata.

type User 

type User struct {
	ID         string         `json:"id"`
	Type       string         `json:"type"`
	Attributes UserAttributes `json:"attributes"`
	Links      Links          `json:"links"`
}

User models the OSF current user response.

type UserAttributes 

type UserAttributes struct {
	FullName   string `json:"full_name"`
	GivenName  string `json:"given_name,omitempty"`
	FamilyName string `json:"family_name,omitempty"`
}

UserAttributes carries profile fields returned for an OSF user.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.